spine-framework 0.3.124 → 0.3.126

package/.framework/functions/_shared/agent-runner.ts

@@ -1,549 +1,125 @@
+// CIL[BEGIN chunk_id="agent-runner_module_header_1784488696" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Agent runner module header with imports and type contracts"]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare module dependencies and the core TypeScript interfaces used by agent-runner"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/functions/_shared/db.ts,.framework/src/components/ui/ItemListView.tsx,.framework/functions/apps.ts,.framework/functions/integration-routes.ts,.framework/functions/system.ts,.framework/functions/auth.ts,.framework/cli/commands/agents.ts,.framework/functions/types.ts,.framework/cli/commands/migrate.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="imports and TypeScript interfaces" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports CoreContext, adminDb, emitAudit, createRecord and defines AgentConfig, InferenceResult, ToolCall, ToolResult" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: none. Direct callees: adminDb(.framework/functions/_shared/db.ts),imports(.framework/src/components/ui/ItemListView.tsx),create(.framework/functions/apps.ts),interfaces(.framework/functions/integration-routes.ts),types(.framework/functions/system.ts),context(.framework/functions/auth.ts). Related files: .framework/functions/_shared/db.ts,.framework/src/components/ui/ItemListView.tsx,.framework/functions/apps.ts,.framework/functions/integration-routes.ts,.framework/functions/system.ts,.framework/functions/auth.ts,.framework/cli/commands/agents.ts,.framework/functions/types.ts,.framework/cli/commands/migrate.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: none. Total affected: 0." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [none] and callees [adminDb(.framework/functions/_shared/db.ts),imports(.framework/src/components/ui/ItemListView.tsx),create(.framework/functions/apps.ts),interfaces(.framework/functions/integration-routes.ts),types(.framework/functions/system.ts),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 /// <reference types="node" />
-/**
- * @module agent-runner
- * @audience both
- * @layer shared-core
- * @stability stable
- *
- * AI agent inference orchestrator with RAG, tool dispatch, and confidence-based
- * escalation. All agent behavior is defined via JSONB configuration stored in
- * existing schema tables — no dedicated migrations are needed.
- *
- * Configuration resolution chain (highest to lowest priority):
- *   1. `thread.data.agent_id` → `thread.type.design_schema.default_agent_id`
- *   2. `thread.data.prompt_config_id` → `agent.metadata.default_prompt_config_id`
- *
- * Inference loop (per `runAgent` call):
- *   1. `resolveAgentConfig` — resolve agent + prompt_config from thread
- *   2. Save user message to `messages` table
- *   3. `executeAgentInference` — iterative tool-call loop (max 5 iterations):
- *      a. `buildContext` — assemble system prompt + RAG + history + tools
- *      b. `callInference` — call OpenAI-compatible API (or return mock)
- *      c. `dispatchTools` — execute any tool_calls via actions table
- *      d. Rebuild context with tool results and repeat
- *   4. Confidence check — if below threshold, `handleEscalation`
- *   5. Save agent response to `messages` table
- *   6. Emit `agent.inference.completed` audit log
- *
- * Environment variables used by `callInference`:
- *   - `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `LLM_API_KEY` — LLM auth
- *   - `OPENAI_BASE_URL` / `LLM_BASE_URL` — API base URL (default: OpenAI)
- *   - `LLM_DEFAULT_MODEL` — model name fallback (default: 'gpt-4o')
- *
- * INVARIANT: if no API key is set, `callInference` returns a mock response
- *   instead of throwing — safe for local development without credentials.
- * INVARIANT: `runAgent` throws on critical failures (config missing, inference
- *   error) — callers must handle the rejection.
- * INVARIANT: `resolveAgentConfig` returns null (not throws) on missing config;
- *   `runAgent` converts this to a throw.
- *
- * @seeAlso pipeline-runner.ts (tool dispatch calls runPipeline for run_pipeline tool)
- * @seeAlso audit.ts (emitAudit for agent.inference.* events)
- * @seeAlso index.ts (runAgent, resolveAgentConfig re-exported)
- */
-
+import { createHash } from 'crypto'
 import { CoreContext } from './middleware'
 import { adminDb } from './db'
-import { emitAudit } from './audit'
+import { emitAudit, emitSpan } from './audit'
+import { emitOutcome } from './outcomes'
+import { withSpan } from './tracing'
 import { create as createRecord } from '../admin-data'
-
-// ─── TYPES ───────────────────────────────────────────────────────────────
-
-/**
- * Resolved agent configuration bundle. Output of `resolveAgentConfig`.
- * Passed to `executeAgentInference` and `buildContext`.
- *
- * @outputSpec agent: ai_agents row (system_prompt, model_config, metadata)
- * @outputSpec promptConfig: prompt_configs row (context_template,
- *   knowledge_sources, available_tools, confidence_threshold, escalation_*)
- * @outputSpec thread: threads row with joined type record
- * @outputSpec threadType: types row (design_schema.default_agent_id)
- */
-export interface AgentConfig {
-  agent: any
-  promptConfig: any
-  thread: any
-  threadType: any
-}
-
-/**
- * Structured result from a single LLM inference call.
- *
- * @outputSpec content: string — agent response text
- * @outputSpec confidence: number — 0-1 score; derived from logprobs or 0.70 default
- * @outputSpec tool_calls: ToolCall[] | undefined — tools the model wants to call
- * @outputSpec metadata: { model, usage, finish_reason } | undefined
- */
-export interface InferenceResult {
-  content: string
-  confidence: number
-  tool_calls?: ToolCall[]
-  metadata?: Record<string, any>
-}
-
-/**
- * A single tool invocation requested by the LLM in an `InferenceResult`.
- *
- * @inputSpec tool: string — action.slug to look up in the actions table
- * @inputSpec params: Record<string, any> — parsed from OpenAI function call arguments
- * @inputSpec id: string — opaque tool_call ID from the LLM response
- */
-export interface ToolCall {
-  tool: string
-  params: Record<string, any>
-  id: string
-}
-
-/**
- * Result of executing a single `ToolCall`.
- *
- * @outputSpec tool: string — mirrors ToolCall.tool
- * @outputSpec result: any — handler return value on success; null on error
- * @outputSpec error: string | undefined — error message if execution failed
- * @outputSpec id: string — mirrors ToolCall.id for correlation
- */
-export interface ToolResult {
-  tool: string
-  result: any
-  error?: string
-  id: string
-}
-
-// ─── PRIMARY EXPORTS ────────────────────────────────────────────────────────────
-
-/**
- * Main entry point: run a full agent inference cycle for a user message.
- *
- * Saves the user message, runs the inference loop (with tool calls), checks
- * confidence, saves the agent response, and emits audit logs.
- *
- * @param threadId - UUID of the thread to run inference on
- * @param userMessage - Raw message text from the user
- * @param ctx - CoreContext with accountId, principal, requestId
- * @returns Promise<any> — the saved agent message record from the `messages` table
- * @throws Error — if agent config cannot be resolved, or LLM inference fails
- * @inputSpec threadId: string — valid UUID in threads table
- * @inputSpec userMessage: string — non-empty message text
- * @inputSpec ctx.accountId: string | null — used to scope DB lookups
- * @outputSpec messages row — the inserted agent reply with content and metadata
- * @sideEffects DB write: inserts 2 messages rows (user + agent)
- * @sideEffects DB write: emitAudit (agent.inference.completed or agent.inference.failed)
- * @sideEffects HTTP call: callInference (LLM API)
- * @sideEffects DB write (conditional): handleEscalation if confidence < threshold
- * @calledBy functions/ai-agents.ts handler for POST ?action=run
- * @calledBy v2-custom/ import callers
- * @calls resolveAgentConfig, saveMessage, executeAgentInference,
- *   handleEscalation, emitAudit
- * @testUnit tests/unit/agent-runner.test.ts
- * @testIntegration tests/integration/agent-runner.test.ts
- *
- * @example API handler usage
- * ```ts
- * import { runAgent } from './_shared/index'
- * const agentMsg = await runAgent(body.thread_id, body.message, ctx)
- * return agentMsg
- * ```
- */
-export async function runAgent(
-  threadId: string,
+import { callOpenAIEmbeddings, callOpenAIChat } from './llm'
+import { execute as executeOutbound } from '../integration-outbound'
+// CIL[END chunk_id="agent-runner_module_header_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_buildcontext_1784488696" type="function" identity="buildContext" parent="none"]
+// CIL[DOC-MACRO purpose="Assemble the full prompt context for an inference call"]
+// CIL[DOC-RESPONSIBILITY responsibility="Build context string from system prompt, template, RAG, history, tool results, tools list, and user message"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/src/types/auth.ts,.framework/functions/auth.ts,custom/apps/cortex/functions/custom_kb-chunker-test.ts,.framework/functions/item-progress.ts,.framework/src/components/runtime/DataDetailPage.tsx,custom/apps/cortex/pages/community/CommunityPage.tsx,.framework/cli/context.ts"]
+// CIL[DOC-CONTRACT inputs="config: AgentConfig\nuserMessage: string\ntoolResults: ToolResult[]\nctx: CoreContext" outputs="{ context, retrievedSources, meanSimilarity }" errors="catches retrieveKnowledge errors" side_effects="DB reads for knowledge and history"]
+// CIL[DOC-MICRO logic_summary="Concatenates system prompt, optional context template, retrieved knowledge, conversation history, tool results, available tools, and current message" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: executeAgentInference,runAgent. Direct callees: User(.framework/src/types/auth.ts),context(.framework/functions/auth.ts),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts),retrieveKnowledge,list(.framework/functions/item-progress.ts),getConversationHistory,title(.framework/src/components/runtime/DataDetailPage.tsx),Message(custom/apps/cortex/pages/community/CommunityPage.tsx). Related files: .framework/src/types/auth.ts,.framework/functions/auth.ts,custom/apps/cortex/functions/custom_kb-chunker-test.ts,.framework/functions/item-progress.ts,.framework/src/components/runtime/DataDetailPage.tsx,custom/apps/cortex/pages/community/CommunityPage.tsx,.framework/cli/context.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: executeAgentInference,runAgent. Total affected: 2." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [executeAgentInference,runAgent] and callees [User(.framework/src/types/auth.ts),context(.framework/functions/auth.ts),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts),retrieveKnowledge,list(.framework/functions/item-progress.ts),getConversationHistory,title(.framework/src/components/runtime/DataDetailPage.tsx),Message(custom/apps/cortex/pages/community/CommunityPage.tsx)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+async function buildContext(
+  config: AgentConfig,
   userMessage: string,
+  toolResults: ToolResult[],
   ctx: CoreContext
-): Promise<any> {
-  const startTime = Date.now()
-
-  try {
-    // 1. Resolve configurations (thread → agent → prompt config)
-    const config = await resolveAgentConfig(threadId, ctx)
-    if (!config) {
-      throw new Error(`Could not resolve agent configuration for thread ${threadId}`)
+): Promise<{ context: string; retrievedSources: any[]; meanSimilarity: number }> {
+  return withSpan(ctx, 'agent.build_context', async (ctx) => {
+    const { agent, promptConfig, thread } = config
+    let context = `${agent.system_prompt || 'You are a helpful assistant.'}\n\n`
+    if (promptConfig.context_template) {
+      context += `${promptConfig.context_template}\n\n`
     }
-
-    const { agent, promptConfig, thread, threadType } = config
-
-    // Resolve the message type from the thread type so support/community threads
-    // save replies with the correct type (and therefore correct permissions).
-    const replyTypeSlug = getReplyTypeSlug(threadType?.slug)
-
-    // 2. Save user message to thread
-    const userMsg = await saveMessage(threadId, userMessage, 'human', null, ctx, replyTypeSlug)
-
-    // 3. Execute agent with full context
-    const agentResponse = await executeAgentInference(
-      config,
-      userMessage,
-      ctx
-    )
-
-    // 4. Check confidence and escalate if needed
-    const isEscalated = agentResponse.confidence < (promptConfig.confidence_threshold || 0)
-    if (isEscalated) {
-      await handleEscalation(
-        threadId,
-        agentResponse.confidence,
-        promptConfig,
+    let retrievedSources: any[] = []
+    let meanSimilarity = 0
+    const retrievalPolicy = promptConfig.metadata?.retrieval_policy || {}
+    try {
+      const { docs, meanSimilarity: ms } = await retrieveKnowledge(
+        userMessage,
+        promptConfig.knowledge_sources || [],
+        ctx.accountId!,
+        retrievalPolicy,
         ctx
       )
-    }
-
-    // 5. Save agent response — include retrieved_sources + retrieval_confidence
-    //    so the feedback capture pipeline and the Portal UI can access them.
-    const agentMsg = await saveMessage(
-      threadId,
-      agentResponse.content,
-      'agent',
-      {
-        confidence: agentResponse.confidence,
-        retrieval_confidence: agentResponse.retrievalConfidence,
-        retrieved_sources: (agentResponse.retrievedSources || []).map((s: any) => ({
-          document_id: s.document_id,
-          title: s.title,
-          similarity: s.similarity,
-          item_type: s.item_type,
-          vector_type: s.vector_type,
-        })),
-        tool_calls: agentResponse.tool_calls,
-        agent_id: agent.id,
-        prompt_config_id: promptConfig.id,
-        sender_type: 'agent',
-        escalated: isEscalated,
-      },
-      ctx,
-      replyTypeSlug
-    )
-
-    // 6. Emit audit log
-    await emitAudit(ctx, 'agent.inference.completed', {
-      type: 'agent_message',
-      id: agentMsg.id,
-      account_id: ctx.accountId ?? undefined
-    }, {
-      thread_id: threadId,
-      agent_id: agent.id,
-      confidence: agentResponse.confidence,
-      retrieval_confidence: agentResponse.retrievalConfidence,
-      sources_count: agentResponse.retrievedSources?.length || 0,
-      has_tool_calls: !!agentResponse.tool_calls?.length,
-      duration_ms: Date.now() - startTime
-    })
-
-    return agentMsg
-
-  } catch (error: any) {
-    // Log failure
-    await emitAudit(ctx, 'agent.inference.failed', {
-      type: 'agent_message',
-      id: 'failed',
-      account_id: ctx.accountId ?? undefined
-    }, {
-      thread_id: threadId,
-      error: error.message
-    })
-
-    throw error
-  }
-}
-
-/**
- * Resolves the agent, prompt config, thread, and thread type for a given thread.
- *
- * Resolution priority:
- *   - `agent_id`: `thread.data.agent_id` → `thread.type.design_schema.default_agent_id`
- *   - `prompt_config_id`: `thread.data.prompt_config_id` →
- *     `agent.metadata.default_prompt_config_id`
- *
- * Returns `null` (does not throw) when any required record is missing. `runAgent`
- * converts a null return to a thrown Error.
- *
- * @param threadId - UUID of the thread
- * @param ctx - CoreContext (requestId used for error logging)
- * @returns Promise<AgentConfig | null> — null if config cannot be resolved
- * @throws never — errors logged to console, returns null
- * @inputSpec threadId: string — valid UUID in threads table
- * @outputSpec AgentConfig | null
- * @sideEffects DB reads: threads (with type join), ai_agents, prompt_configs
- * @calledBy runAgent
- * @testUnit tests/unit/agent-runner.test.ts — 'resolveAgentConfig'
- */
-export async function resolveAgentConfig(
-  threadId: string,
-  ctx: CoreContext
-): Promise<AgentConfig | null> {
-  // Load thread with its type
-  const { data: thread, error: threadError } = await adminDb
-    .from('threads')
-    .select('*, type:types(*)')
-    .eq('id', threadId)
-    .single()
-
-  if (threadError || !thread) {
-    console.error(`Thread not found: ${threadId}`, threadError)
-    return null
-  }
-
-  const threadType = thread.type
-  const threadData = thread.data || {}
-
-  // Resolve agent_id: thread.data > thread.type.design_schema.default_agent_id
-  let agentId = threadData.agent_id
-  if (!agentId && threadType?.design_schema?.default_agent_id) {
-    agentId = threadType.design_schema.default_agent_id
-  }
-
-  if (!agentId) {
-    console.error(`No agent assigned to thread ${threadId}`)
-    return null
-  }
-
-  // Load agent
-  const { data: agent, error: agentError } = await adminDb
-    .from('ai_agents')
-    .select('*')
-    .eq('id', agentId)
-    .eq('is_active', true)
-    .single()
-
-  if (agentError || !agent) {
-    console.error(`Agent not found: ${agentId}`, agentError)
-    return null
-  }
-
-  const agentMetadata = agent.metadata || {}
-
-  // Resolve prompt_config_id: thread.data > agent.metadata.default_prompt_config_id
-  let promptConfigId = threadData.prompt_config_id
-  if (!promptConfigId && agentMetadata.default_prompt_config_id) {
-    promptConfigId = agentMetadata.default_prompt_config_id
-  }
-
-  if (!promptConfigId) {
-    console.error(`No prompt config for thread ${threadId}`)
-    return null
-  }
-
-  // Load prompt config
-  const { data: promptConfig, error: configError } = await adminDb
-    .from('prompt_configs')
-    .select('*')
-    .eq('id', promptConfigId)
-    .eq('is_active', true)
-    .single()
-
-  if (configError || !promptConfig) {
-    console.error(`Prompt config not found: ${promptConfigId}`, configError)
-    return null
-  }
-
-  return { agent, promptConfig, thread, threadType }
-}
-
-// ─── INFERENCE LOOP ─────────────────────────────────────────────────────────────
-
-/**
- * Runs the iterative inference loop: build context → call LLM → dispatch tools
- * → rebuild context → repeat (up to `maxToolIterations`).
- *
- * Returns early when the LLM response has no tool_calls. Stops on last
- * iteration with a note appended if any tool failed.
- *
- * @param config - Resolved AgentConfig
- * @param userMessage - Original user message text
- * @param ctx - CoreContext
- * @param maxToolIterations - Maximum tool-call loops (default: 5)
- * @returns Promise<InferenceResult> — final LLM response with content and confidence
- * @throws Error('Max tool iterations reached') if loop exhausted without convergence
- * @sideEffects HTTP calls: callInference (per iteration)
- * @sideEffects DB reads: messages (conversation history), embeddings (RAG)
- * @calledBy runAgent
- * @calls buildContext, callInference, dispatchTools
- */
-async function executeAgentInference(
-  config: AgentConfig,
-  userMessage: string,
-  ctx: CoreContext,
-  maxToolIterations: number = 5
-): Promise<InferenceResult & { retrievedSources: any[]; retrievalConfidence: number }> {
-  const { agent, promptConfig } = config
-
-  // Build initial context — captures retrieved sources for feedback capture
-  let { context, retrievedSources, meanSimilarity } = await buildContext(config, userMessage, [], ctx)
-
-  for (let iteration = 0; iteration < maxToolIterations; iteration++) {
-    const inferenceResult = await callInference(context, agent, promptConfig, ctx)
-
-    if (!inferenceResult.tool_calls || inferenceResult.tool_calls.length === 0) {
-      // Composite confidence: 60% LLM logprobs + 40% retrieval similarity
-      // When logprobs are absent, be conservative: default 0.70 instead of 0.85
-      // If mean retrieval similarity < 0.40, cap composite at 0.60
-      // If mean retrieval similarity < 0.25, cap composite at 0.45 (very poor retrieval)
-      const llmConf = inferenceResult.confidence ?? 0.70
-      let compositeConf: number
-      if (meanSimilarity < 0.25 && meanSimilarity > 0) {
-        compositeConf = Math.min(llmConf * 0.6 + meanSimilarity * 0.4, 0.45)
-      } else if (meanSimilarity < 0.40 && meanSimilarity > 0) {
-        compositeConf = Math.min(llmConf * 0.6 + meanSimilarity * 0.4, 0.60)
-      } else {
-        compositeConf = llmConf * 0.6 + Math.min(meanSimilarity, 1) * 0.4
-      }
-
-      return {
-        ...inferenceResult,
-        confidence: Math.min(Math.max(compositeConf, 0), 1),
-        retrievedSources,
-        retrievalConfidence: meanSimilarity,
+      retrievedSources = docs
+      meanSimilarity = ms
+      if (docs.length > 0) {
+        context += '## Relevant Information\n'
+        docs.forEach((doc, i) => {
+          const sourceLabel = doc.title ? `[${i + 1}] ${doc.title}` : `[${i + 1}]`
+          context += `${sourceLabel}\n${doc.content}\n\n`
+        })
       }
+    } catch (err) {
+      console.warn('retrieveKnowledge failed — proceeding without context:', err)
     }
-
-    const toolResults = await dispatchTools(inferenceResult.tool_calls, ctx)
-    const rebuilt = await buildContext(config, userMessage, toolResults, ctx)
-    context = rebuilt.context
-    if (rebuilt.retrievedSources.length) {
-      retrievedSources = rebuilt.retrievedSources
-      meanSimilarity = rebuilt.meanSimilarity
+    const history = await getConversationHistory(thread.id, promptConfig.max_history_messages || 20)
+    if (history.length > 0) {
+      context += '## Conversation History\n'
+      history.forEach(msg => {
+        const role = msg.data?.message_type === 'human' ? 'User' : 'Assistant'
+        context += `${role}: ${msg.content}\n`
+      })
+      context += '\n'
     }
-
-    const hasErrors = toolResults.some(r => r.error)
-    if (hasErrors && iteration === maxToolIterations - 1) {
-      inferenceResult.content += '\n\n[Note: Some tools failed to execute.]'
-      return { ...inferenceResult, retrievedSources, retrievalConfidence: meanSimilarity }
+    if (toolResults.length > 0) {
+      context += '## Tool Results\n'
+      toolResults.forEach(result => {
+        if (result.error) {
+          context += `Tool "${result.tool}" failed: ${result.error}\n`
+        } else {
+          context += `Tool "${result.tool}" result: ${JSON.stringify(result.result)}\n`
+        }
+      })
+      context += '\n'
     }
-  }
-
-  throw new Error('Max tool iterations reached')
-}
-
-/**
- * Assembles the full prompt context string for a single inference call.
- *
- * Context sections (in order):
- *   1. `agent.system_prompt` (or default 'You are a helpful assistant.')
- *   2. `promptConfig.context_template` (if set)
- *   3. Retrieved knowledge via `retrieveKnowledge` (RAG, if knowledge_sources set)
- *   4. Conversation history via `getConversationHistory`
- *   5. Tool results from previous iteration (if any)
- *   6. Available tools list from `promptConfig.available_tools`
- *   7. Current user message
- *
- * @param config - AgentConfig with agent, promptConfig, thread
- * @param userMessage - Current user message
- * @param toolResults - Results from previous tool dispatch iteration
- * @param ctx - CoreContext
- * @returns Promise<string> — assembled prompt context string
- * @throws never — returns partial context on sub-call failure
- * @sideEffects DB reads: embeddings (retrieveKnowledge), messages (history)
- * @calledBy executeAgentInference (per iteration)
- * @calls retrieveKnowledge, getConversationHistory
- */
-async function buildContext(
-  config: AgentConfig,
-  userMessage: string,
-  toolResults: ToolResult[],
-  ctx: CoreContext
-): Promise<{ context: string; retrievedSources: any[]; meanSimilarity: number }> {
-  const { agent, promptConfig, thread } = config
-
-  // 1. System prompt (from agent)
-  let context = `${agent.system_prompt || 'You are a helpful assistant.'}\n\n`
-
-  // 2. Context template (from prompt config)
-  if (promptConfig.context_template) {
-    context += `${promptConfig.context_template}\n\n`
-  }
-
-  // 3. Retrieved knowledge (RAG)
-  // Always attempt retrieval — even with empty knowledge_sources (full scope search)
-  let retrievedSources: any[] = []
-  let meanSimilarity = 0
-  const retrievalPolicy = promptConfig.metadata?.retrieval_policy || {}
-
-  try {
-    const { docs, meanSimilarity: ms } = await retrieveKnowledge(
-      userMessage,
-      promptConfig.knowledge_sources || [],
-      ctx.accountId!,
-      retrievalPolicy
-    )
-    retrievedSources = docs
-    meanSimilarity = ms
-
-    if (docs.length > 0) {
-      context += '## Relevant Information\n'
-      docs.forEach((doc, i) => {
-        const sourceLabel = doc.title ? `[${i + 1}] ${doc.title}` : `[${i + 1}]`
-        context += `${sourceLabel}\n${doc.content}\n\n`
+    if (promptConfig.available_tools && promptConfig.available_tools.length > 0) {
+      context += '## Available Tools\n'
+      promptConfig.available_tools.forEach((tool: string) => {
+        context += `- ${tool}\n`
       })
+      context += '\n'
     }
-  } catch (err) {
-    console.warn('retrieveKnowledge failed — proceeding without context:', err)
-  }
-
-  // 4. Conversation history
-  const history = await getConversationHistory(thread.id, promptConfig.max_history_messages || 20)
-  if (history.length > 0) {
-    context += '## Conversation History\n'
-    history.forEach(msg => {
-      const role = msg.data?.message_type === 'human' ? 'User' : 'Assistant'
-      context += `${role}: ${msg.content}\n`
-    })
-    context += '\n'
-  }
-
-  // 5. Tool results (if any)
-  if (toolResults.length > 0) {
-    context += '## Tool Results\n'
-    toolResults.forEach(result => {
-      if (result.error) {
-        context += `Tool "${result.tool}" failed: ${result.error}\n`
-      } else {
-        context += `Tool "${result.tool}" result: ${JSON.stringify(result.result)}\n`
-      }
-    })
-    context += '\n'
-  }
-
-  // 6. Available tools (if configured)
-  if (promptConfig.available_tools && promptConfig.available_tools.length > 0) {
-    context += '## Available Tools\n'
-    promptConfig.available_tools.forEach((tool: string) => {
-      context += `- ${tool}\n`
-    })
-    context += '\n'
-  }
-
-  // 7. Current user message
-  context += `## Current Message\nUser: ${userMessage}\n\nAssistant: `
-
-  return { context, retrievedSources, meanSimilarity }
+    context += `## Current Message\nUser: ${userMessage}\n\nAssistant: `
+    return { context, retrievedSources, meanSimilarity }
+  }, { onEnd: emitSpan })
 }
-
-// ─── KNOWLEDGE & HISTORY ───────────────────────────────────────────────────────────
-
-/**
- * Retrieves relevant documents from the `embeddings` table for RAG.
- *
- * Strategy (tiered):
- *   1. Generate a query embedding via the OpenAI embeddings API.
- *   2. Call the `match_embeddings` Postgres RPC (vector cosine similarity).
- *   3. Deduplicate by document_id — keep best-matching chunk per article.
- *   4. Enrich with item titles from the `items` table.
- *   5. Fall back to full-text search if the embedding API is unavailable or
- *      the RPC call fails (guarantees graceful degradation in dev/test).
- *
- * Account scoping:
- *   - Always includes the requesting account's embeddings.
- *   - Always includes the platform KB account (spine-system), excluding
- *     rows where metadata.security_level = 'restricted'.
- *   - `knowledgeSources` optionally narrows to specific document UUIDs
- *     (prompt_config.knowledge_sources); omit or pass [] for full scope.
- *
- * @param query - User message text to embed and search
- * @param knowledgeSources - Optional document UUIDs to restrict search scope
- * @param accountId - Requesting account for scoped access
- * @returns Promise<any[]> — enriched result rows (id, title, content, similarity)
- * @throws never — falls back to text search or [] on any failure
- * @sideEffects HTTP call to OpenAI embeddings API (if API key present)
- * @sideEffects DB read: match_embeddings RPC + items table
- * @calledBy buildContext (if promptConfig.knowledge_sources is non-empty)
- */
+// CIL[END chunk_id="agent-runner_buildcontext_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_retrieveknowledge_1784488696" type="function" identity="retrieveKnowledge" parent="none"]
+// CIL[DOC-MACRO purpose="Retrieve relevant documents from the embeddings table for RAG"]
+// CIL[DOC-RESPONSIBILITY responsibility="Run vector similarity search via OpenAI embeddings and match_embeddings RPC, with security filtering and text fallback"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/functions/item-progress.ts,.framework/migrations/001_schema.sql,.framework/functions/_shared/db.ts,.framework/src/pages/admin/TypesPage.tsx,custom/apps/cortex/functions/custom_cil-embeddings.ts,.framework/src/components/runtime/DataDetailPage.tsx,custom/apps/cortex/functions/custom_kb-chunker-test.ts,.framework/functions/auth.ts,.framework/migrations/027_embedding_lifecycle.sql,.framework/functions/embeddings.ts"]
+// CIL[DOC-CONTRACT inputs="query: string\nknowledgeSources: string[]\naccountId: string\nretrievalPolicy?: { item_types?: string[], vector_types?: string[], max_security_level?: string, require_approved?: boolean, project_ids?: string[] }\nctx?: CoreContext" outputs="{ docs, meanSimilarity }" errors="returns empty docs on any failure" side_effects="HTTP call to OpenAI embeddings API; DB RPC and items read"]
+// CIL[DOC-MICRO logic_summary="Generates query embedding, runs multi-vector match_embeddings (larger match_count when project_ids are filtered), filters by security level and optional CIL project_id, deduplicates by document, and falls back to full-text search" notable_decisions="[]"]
+// CIL[DOC-LEARNING topic="agent-runner:retrieval_security_level" content="CIL chunks are stored with security_level 'internal'. A prompt_config retrieval_policy with max_security_level='external' filters them out, causing the agent to see no codebase context. Set max_security_level to 'internal' or higher for CIL-augmented support agents."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: buildContext,executeAgentInference,runAgent. Direct callees: get(.framework/functions/item-progress.ts),embeddings(.framework/migrations/001_schema.sql),adminDb(.framework/functions/_shared/db.ts),Type(.framework/src/pages/admin/TypesPage.tsx),rank(custom/apps/cortex/functions/custom_cil-embeddings.ts),title(.framework/src/components/runtime/DataDetailPage.tsx),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts),context(.framework/functions/auth.ts). Related files: .framework/functions/item-progress.ts,.framework/migrations/001_schema.sql,.framework/functions/_shared/db.ts,.framework/src/pages/admin/TypesPage.tsx,custom/apps/cortex/functions/custom_cil-embeddings.ts,.framework/src/components/runtime/DataDetailPage.tsx,custom/apps/cortex/functions/custom_kb-chunker-test.ts,.framework/functions/auth.ts,.framework/migrations/027_embedding_lifecycle.sql,.framework/functions/embeddings.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: buildContext,executeAgentInference,runAgent. Total affected: 3." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [buildContext,executeAgentInference,runAgent] and callees [get(.framework/functions/item-progress.ts),embeddings(.framework/migrations/001_schema.sql),adminDb(.framework/functions/_shared/db.ts),Type(.framework/src/pages/admin/TypesPage.tsx),rank(custom/apps/cortex/functions/custom_cil-embeddings.ts),title(.framework/src/components/runtime/DataDetailPage.tsx),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function retrieveKnowledge(
   query: string,
   knowledgeSources: string[],
@@ -553,47 +129,33 @@ async function retrieveKnowledge(
     vector_types?: string[]
     max_security_level?: 'external' | 'internal' | 'restricted'
     require_approved?: boolean
-  }
+    project_ids?: string[]
+  },
+  ctx?: CoreContext
 ): Promise<{ docs: any[]; meanSimilarity: number }> {
+  return withSpan(ctx || ({ trace: undefined } as CoreContext), 'agent.retrieve_knowledge', async (ctx) => {
   const SIMILARITY_THRESHOLD = 0.15
   const MATCH_COUNT = 8
   const policy = retrievalPolicy || {}
   const vectorTypesToSearch = policy.vector_types?.length ? policy.vector_types : ['semantic']
   const maxSecurityLevel = policy.max_security_level || 'internal'
-
-  // Security level ordering: external < internal < restricted
   const SECURITY_ORDER: Record<string, number> = { external: 0, internal: 1, restricted: 2 }
   const maxSecurityRank = SECURITY_ORDER[maxSecurityLevel] ?? 1
-
-  // ── Tier 1: vector similarity via match_embeddings RPC ──────────────────
+  const projectIds = policy.project_ids || []
+  const hasProjectFilter = projectIds.length > 0
   try {
-    const apiKey = process.env.OPENAI_API_KEY || process.env.LLM_API_KEY
-    const baseUrl = process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1'
-    if (!apiKey) throw new Error('no_api_key')
-
-    // Resolve platform account — always include spine-system KB
     const { data: platformAccount } = await adminDb
       .from('accounts').select('id').eq('slug', 'spine-system').maybeSingle()
     const accountIds: string[] = [accountId]
     if (platformAccount?.id && platformAccount.id !== accountId) accountIds.push(platformAccount.id)
-
-    // Generate query embedding
-    const embedRes = await fetch(`${baseUrl}/embeddings`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
-      body: JSON.stringify({ model: 'text-embedding-3-small', input: query }),
-    })
-    if (!embedRes.ok) throw new Error(`embed_api_${embedRes.status}`)
-    const embedJson: any = await embedRes.json()
+    const embedJson = await callOpenAIEmbeddings(ctx, [query])
     const queryEmbedding: number[] = embedJson.data?.[0]?.embedding || []
     if (!queryEmbedding.length) throw new Error('empty_embedding')
-
-    // Multi-vector search: run all declared vector types and merge
     const allMatches: any[] = []
     for (const vt of vectorTypesToSearch) {
       const { data: matches, error: rpcError } = await adminDb.rpc('match_embeddings', {
         query_embedding: `[${queryEmbedding.join(',')}]`,
-        match_count: MATCH_COUNT * 3,
+        match_count: MATCH_COUNT * (hasProjectFilter ? 5 : 3),
         filter_account_ids: accountIds,
         filter_vector_type: vt,
         similarity_threshold: SIMILARITY_THRESHOLD,
@@ -602,23 +164,26 @@ async function retrieveKnowledge(
       if (rpcError) throw new Error(`rpc_${rpcError.message}`)
       allMatches.push(...(matches || []))
     }
-
-    // Hard security filter
     const filtered = allMatches.filter((r: any) => {
       if (r.similarity < SIMILARITY_THRESHOLD) return false
       const secLevel = r.metadata?.security_level || 'internal'
       const rank = SECURITY_ORDER[secLevel] ?? 1
       if (rank > maxSecurityRank) return false
       if (r.account_id !== accountId && secLevel === 'restricted') return false
+      // When project_ids are specified, only keep cil_chunk embeddings whose
+      // metadata.project_id is in the allowed list. Non-cil_chunk items pass.
+      if (hasProjectFilter) {
+        const itemType = r.metadata?.item_type
+        if (itemType === 'cil_chunk') {
+          const projectId = r.metadata?.project_id
+          if (!projectId || !projectIds.includes(projectId)) return false
+        }
+      }
       return true
     })
-
-    // Narrow to knowledgeSources if specified
     const scoped = knowledgeSources.length > 0
       ? filtered.filter((r: any) => knowledgeSources.includes(r.document_id))
       : filtered
-
-    // Deduplicate — best chunk per document across all vector types
     const bestByDoc = new Map<string, any>()
     for (const r of scoped) {
       const existing = bestByDoc.get(r.document_id)
@@ -627,14 +192,11 @@ async function retrieveKnowledge(
     const deduped = [...bestByDoc.values()]
       .sort((a, b) => b.similarity - a.similarity)
       .slice(0, MATCH_COUNT)
-
     if (!deduped.length) return { docs: [], meanSimilarity: 0 }
-
-    // If top result < 0.50 and summary not already included, try summary fallback
     if (deduped[0]?.similarity < 0.50 && !vectorTypesToSearch.includes('summary')) {
       const { data: summaryMatches } = await adminDb.rpc('match_embeddings', {
         query_embedding: `[${queryEmbedding.join(',')}]`,
-        match_count: MATCH_COUNT,
+        match_count: MATCH_COUNT * (hasProjectFilter ? 5 : 1),
         filter_account_ids: accountIds,
         filter_vector_type: 'summary',
         similarity_threshold: SIMILARITY_THRESHOLD,
@@ -649,12 +211,9 @@ async function retrieveKnowledge(
     const finalDocs = [...bestByDoc.values()]
       .sort((a, b) => b.similarity - a.similarity)
       .slice(0, MATCH_COUNT)
-
-    // Enrich with item titles
     const { data: items } = await adminDb
       .from('items').select('id, title').in('id', finalDocs.map((r: any) => r.document_id))
     const itemMap = new Map((items || []).map((i: any) => [i.id, i]))
-
     const docs = finalDocs.map((r: any) => ({
       document_id: r.document_id,
       content: r.content,
@@ -664,46 +223,51 @@ async function retrieveKnowledge(
       item_type: r.metadata?.item_type || '',
       vector_type: r.metadata?.vector_type || '',
     }))
-
     const meanSimilarity = docs.length
       ? docs.reduce((sum: number, d: any) => sum + d.similarity, 0) / docs.length
       : 0
-
     return { docs, meanSimilarity }
-
   } catch (vectorErr: any) {
-    // ── Tier 2: full-text fallback ──────────────────────────────────────
     if (vectorErr.message !== 'no_api_key') {
       console.warn('retrieveKnowledge vector search failed, falling back to text search:', vectorErr.message)
     }
-    const baseQuery = adminDb
+    let baseQuery = adminDb
       .from('embeddings')
       .select('document_id, content, metadata, account_id')
       .eq('account_id', accountId)
       .eq('metadata->>vector_type', 'semantic')
-      .not('revoked_at', 'is', null)
+      .is('revoked_at', null)
       .textSearch('content', query, { type: 'websearch', config: 'english' })
       .limit(5)
+    if (policy.item_types?.length) {
+      baseQuery = baseQuery.in('metadata->>item_type', policy.item_types)
+    }
+    if (hasProjectFilter) {
+      const ids = projectIds.map((id: string) => `${id}`).join(',')
+      baseQuery = baseQuery.or(`metadata->>item_type.neq.cil_chunk,metadata->>project_id.in.(${ids})`)
+    }
     const q = knowledgeSources.length > 0 ? baseQuery.in('document_id', knowledgeSources) : baseQuery
     const { data: docs, error } = await q
     if (error) { console.error('Knowledge retrieval fallback failed:', error); return { docs: [], meanSimilarity: 0 } }
     return { docs: docs || [], meanSimilarity: 0 }
   }
+}, { onEnd: emitSpan })
 }
-
-/**
- * Loads the most recent N messages from a thread, ordered chronologically.
- *
- * Returns messages in ascending order (oldest first) for context assembly.
- * Returns empty array on error (never throws).
- *
- * @param threadId - UUID of the thread
- * @param limit - Maximum number of messages to return (from promptConfig.max_history_messages)
- * @returns Promise<any[]> — array of messages rows ordered oldest-first
- * @throws never — returns [] on failure
- * @sideEffects DB read: messages table
- * @calledBy buildContext
- */
+// CIL[END chunk_id="agent-runner_retrieveknowledge_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_getconversationhistory_1784488696" type="function" identity="getConversationHistory" parent="none"]
+// CIL[DOC-MACRO purpose="Load recent messages for a thread in chronological order"]
+// CIL[DOC-RESPONSIBILITY responsibility="Fetch messages from the messages table and return oldest-first"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/functions/_shared/db.ts,.framework/functions/auth.ts,.framework/migrations/001_schema.sql,.framework/src/apps/admin/index.tsx,.framework/src/components/ui/chart.tsx"]
+// CIL[DOC-CONTRACT inputs="threadId: string\nlimit: number" outputs="messages[] ordered oldest-first" errors="returns [] on failure" side_effects="DB read messages table"]
+// CIL[DOC-MICRO logic_summary="Queries messages by thread_id, orders descending, reverses to ascending, and returns result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: buildContext,executeAgentInference,runAgent. Direct callees: adminDb(.framework/functions/_shared/db.ts),context(.framework/functions/auth.ts). Related files: .framework/functions/_shared/db.ts,.framework/functions/auth.ts,.framework/migrations/001_schema.sql,.framework/src/apps/admin/index.tsx,.framework/src/components/ui/chart.tsx." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: buildContext,executeAgentInference,runAgent. Total affected: 3." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [buildContext,executeAgentInference,runAgent] and callees [adminDb(.framework/functions/_shared/db.ts),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function getConversationHistory(
   threadId: string,
   limit: number
@@ -714,101 +278,67 @@ async function getConversationHistory(
     .eq('thread_id', threadId)
     .order('created_at', { ascending: false })
     .limit(limit)
-
   if (error) {
     console.error('Failed to load history:', error)
     return []
   }
-
   return messages?.reverse() || []
 }
-
-// ─── INFERENCE CALL ────────────────────────────────────────────────────────────
-
-/**
- * Calls an OpenAI-compatible chat completions API with the assembled context.
- *
- * Credentials and base URL are loaded from environment variables:
- *   - `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `LLM_API_KEY`
- *   - `OPENAI_BASE_URL` / `LLM_BASE_URL` (default: 'https://api.openai.com/v1')
- *   - `LLM_DEFAULT_MODEL` (default: 'gpt-4o')
- *
- * If no API key is found, returns a mock response instead of throwing.
- * This allows local development without LLM credentials.
- *
- * Tool calls are extracted from `message.tool_calls` and mapped to `ToolCall[]`.
- * Confidence is derived from `logprobs` if available, otherwise defaults to 0.85.
- *
- * @param context - Assembled context string from buildContext
- * @param agent - Agent record with model_config (model, temperature, max_tokens, tools)
- * @param promptConfig - Prompt config record (unused here beyond model overrides)
- * @param ctx - CoreContext (requestId for logging)
- * @returns Promise<InferenceResult> — content, confidence, tool_calls, metadata
- * @throws Error('Inference failed: <status>') on non-2xx HTTP response
- * @sideEffects HTTP call to `${OPENAI_BASE_URL}/chat/completions`
- * @calledBy executeAgentInference (per iteration)
- */
+// CIL[END chunk_id="agent-runner_getconversationhistory_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_callinference_1784488696" type="function" identity="callInference" parent="none"]
+// CIL[DOC-MACRO purpose="Call an OpenAI-compatible chat completions endpoint"]
+// CIL[DOC-RESPONSIBILITY responsibility="Send assembled context to the LLM and return content, confidence, tool_calls, and metadata"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/src/pages/admin/TypesPage.tsx,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/auth.ts,custom/apps/cortex/functions/custom_kb-chunker-test.ts,custom/apps/cortex/functions/custom_cil-callmap.ts,.framework/cli/commands/system.ts"]
+// CIL[DOC-CONTRACT inputs="context: string\nagent: any\npromptConfig: any\nctx: CoreContext" outputs="InferenceResult" errors="throws on non-2xx response" side_effects="HTTP POST to chat completions API"]
+// CIL[DOC-MICRO logic_summary="Builds messages array from context, calls completions, extracts tool_calls and confidence from logprobs or default" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: executeAgentInference,runAgent. Direct callees: Type(.framework/src/pages/admin/TypesPage.tsx),params(.framework/src/components/runtime/DataDetailPage.tsx),context(.framework/functions/auth.ts),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts). Related files: .framework/src/pages/admin/TypesPage.tsx,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/auth.ts,custom/apps/cortex/functions/custom_kb-chunker-test.ts,custom/apps/cortex/functions/custom_cil-callmap.ts,.framework/cli/commands/system.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: executeAgentInference,runAgent. Total affected: 2." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [executeAgentInference,runAgent] and callees [Type(.framework/src/pages/admin/TypesPage.tsx),params(.framework/src/components/runtime/DataDetailPage.tsx),context(.framework/functions/auth.ts),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function callInference(
   context: string,
   agent: any,
   promptConfig: any,
   ctx: CoreContext
 ): Promise<InferenceResult> {
+  return withSpan(ctx, 'agent.inference', async (ctx) => {
   const modelConfig = agent.model_config || {}
-  
-  // Get LLM credentials from environment (safer than DB storage)
-  const apiKey = process.env.OPENAI_API_KEY || process.env.ANTHROPIC_API_KEY || process.env.LLM_API_KEY
-  const baseUrl = process.env.OPENAI_BASE_URL || process.env.LLM_BASE_URL || 'https://api.openai.com/v1'
-  
-  if (!apiKey) {
-    // Fallback: return mock response for development
-    console.warn('No LLM API key found in environment. Set OPENAI_API_KEY or LLM_API_KEY.')
-    return {
-      content: `[Mock Response] Received ${context.length} chars of context. Set OPENAI_API_KEY in .env for live inference.`,
-      confidence: 0.9,
-      tool_calls: undefined,
-      metadata: { mock: true }
-    }
-  }
-
   const model = modelConfig.model || process.env.LLM_DEFAULT_MODEL || 'gpt-4o'
   const temperature = modelConfig.temperature ?? 0.7
   const maxTokens = modelConfig.max_tokens ?? 4000
+  const messages = [
+    { role: 'system', content: context.split('\n\n')[0] },
+    { role: 'user', content: context.split('\n\n').slice(1).join('\n\n') }
+  ]
 
-  // Call OpenAI-compatible API
-  const response = await fetch(`${baseUrl}/chat/completions`, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'Authorization': `Bearer ${apiKey}`
-    },
-    body: JSON.stringify({
-      model,
-      messages: [
-        { role: 'system', content: context.split('\n\n')[0] }, // First paragraph as system
-        { role: 'user', content: context.split('\n\n').slice(1).join('\n\n') } // Rest as user
-      ],
+  let result: any
+  try {
+    result = await callOpenAIChat(ctx, messages, model, {
       temperature,
       max_tokens: maxTokens,
       ...(modelConfig.tools?.length ? { tools: modelConfig.tools, tool_choice: 'auto' } : {})
     })
-  })
-
-  if (!response.ok) {
-    const errorBody = await response.text()
-    throw new Error(`Inference failed: ${response.status} ${response.statusText} - ${errorBody}`)
+  } catch (err: any) {
+    if (err?.message?.includes('not found') || err?.message?.includes('credential')) {
+      console.warn('No OpenAI integration or credential configured, returning mock inference response')
+      return {
+        content: `[Mock Response] Received ${context.length} chars of context. Set OPENAI_API_KEY in .env or configure the openai integration for live inference.`,
+        confidence: 0.9,
+        tool_calls: undefined,
+        metadata: { mock: true }
+      }
+    }
+    throw err
   }
 
-  const result: any = await response.json()
   const message = result.choices?.[0]?.message
-
-  // Extract confidence from logprobs if available, otherwise estimate
-  // Default is conservative (0.70) when logprobs are absent — retrieval quality
-  // should drive the final composite confidence, not an arbitrary high default.
   const confidence = result.choices?.[0]?.logprobs?.content?.[0]?.logprob 
     ? Math.exp(result.choices[0].logprobs.content[0].logprob)
     : 0.70
-
   return {
     content: message?.content || '',
     confidence,
@@ -823,260 +353,253 @@ async function callInference(
       finish_reason: result.choices?.[0]?.finish_reason
     }
   }
+}, { onEnd: emitSpan })
 }
-
-/**
- * Legacy webhook-based inference handler. Calls an arbitrary URL with the
- * config as JSON body. Returns a mock if `config.url` is not set.
- *
- * @deprecated Use `callInference` with environment-based credentials instead.
- * @throws Error on non-2xx HTTP response
- * @sideEffects HTTP call to config.url
- * @calledBy unused (kept for backward compatibility)
- */
+// CIL[END chunk_id="agent-runner_callinference_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_executeinferencehandler_1784488696" type="function" identity="executeInferenceHandler" parent="none"]
+// CIL[DOC-MACRO purpose="Legacy webhook-based inference handler"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch inference to an arbitrary webhook URL for backward compatibility"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/functions/tests.ts,.framework/src/pages/admin/TypesPage.tsx,custom/apps/cortex/functions/custom_kb-chunker-test.ts,.framework/functions/auth.ts,.framework/functions/_shared/webhook-registry.ts,.framework/functions/invites.ts,.framework/functions/item-progress.ts"]
+// CIL[DOC-CONTRACT inputs="config: any\nctx: CoreContext" outputs="JSON response" errors="throws on non-2xx" side_effects="HTTP call to config.url"]
+// CIL[DOC-MICRO logic_summary="Returns mock if url is unset; otherwise POSTs config JSON to url" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="deprecated"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: none. Direct callees: handler(.framework/functions/tests.ts),Type(.framework/src/pages/admin/TypesPage.tsx),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts),context(.framework/functions/auth.ts). Related files: .framework/functions/tests.ts,.framework/src/pages/admin/TypesPage.tsx,custom/apps/cortex/functions/custom_kb-chunker-test.ts,.framework/functions/auth.ts,.framework/functions/_shared/webhook-registry.ts,.framework/functions/invites.ts,.framework/functions/item-progress.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: none. Total affected: 0." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [none] and callees [handler(.framework/functions/tests.ts),Type(.framework/src/pages/admin/TypesPage.tsx),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function executeInferenceHandler(
   config: any,
   ctx: CoreContext
 ): Promise<any> {
   const { url, method = 'POST', headers = {} } = config
-
   if (!url) {
-    // Fallback: return mock response for development
     console.warn('No inference URL configured, returning mock response')
     return {
       content: `[Mock] I received your message. In production, this would call ${config.model} via webhook.`,
       confidence: 0.9
     }
   }
-
-  const response = await fetch(url, {
-    method,
-    headers: {
-      'Content-Type': 'application/json',
-      ...headers
-    },
-    body: JSON.stringify(config)
+  const result = await executeOutbound(ctx, {
+    integration_slug: 'generic-http',
+    action_config: { url, method: method || 'POST', headers, body: config }
   })
-
-  if (!response.ok) {
-    throw new Error(`Inference failed: ${response.status} ${response.statusText}`)
+  if (!result.success) {
+    throw new Error(`Inference failed: ${result.response_status} ${result.response_body}`)
   }
-
-  return await response.json()
+  return result.response_body
 }
-
-// ─── TOOL DISPATCH ────────────────────────────────────────────────────────────
-
-/**
- * Executes a batch of tool calls in sequence, returning results for each.
- *
- * For each tool call:
- *   1. Look up action by `call.tool` (action.slug) in the actions table
- *   2. Call `executeToolAction` to dispatch to the correct handler
- *   3. Push `ToolResult` with success output or error message
- *
- * Individual tool failures are captured in `ToolResult.error` and do NOT
- * halt the batch — all tool calls are attempted.
- *
- * @param toolCalls - Array of ToolCall objects from an InferenceResult
- * @param ctx - CoreContext
- * @returns Promise<ToolResult[]> — one result per input tool call
- * @throws never — per-tool errors captured in result.error
- * @sideEffects DB read: actions table (per tool call)
- * @sideEffects Calls executeToolAction (DB writes, HTTP calls per handler)
- * @calledBy executeAgentInference (after each inference call with tool_calls)
- * @calls executeToolAction
- */
+// CIL[END chunk_id="agent-runner_executeinferencehandler_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_dispatchtools_1784488696" type="function" identity="dispatchTools" parent="none"]
+// CIL[DOC-MACRO purpose="Execute a batch of tool calls in sequence"]
+// CIL[DOC-RESPONSIBILITY responsibility="Look up each tool action and dispatch to executeToolAction, collecting ToolResult entries"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/functions/tests.ts,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/_shared/db.ts,.framework/functions/auth.ts"]
+// CIL[DOC-CONTRACT inputs="toolCalls: ToolCall[]\nctx: CoreContext" outputs="ToolResult[]" errors="none; per-tool errors captured in result.error" side_effects="DB reads actions table; calls handlers; resolves built-in CIL tools directly"]
+// CIL[DOC-MICRO logic_summary="Iterates toolCalls, routes CIL tool slugs directly to executeToolAction, loads other actions by slug, executes handler, and pushes success or error results" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: executeAgentInference,runAgent. Direct callees: handler(.framework/functions/tests.ts),executeToolAction,params(.framework/src/components/runtime/DataDetailPage.tsx),adminDb(.framework/functions/_shared/db.ts),context(.framework/functions/auth.ts). Related files: .framework/functions/tests.ts,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/_shared/db.ts,.framework/functions/auth.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: executeAgentInference,runAgent. Total affected: 2." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [executeAgentInference,runAgent] and callees [handler(.framework/functions/tests.ts),executeToolAction,params(.framework/src/components/runtime/DataDetailPage.tsx),adminDb(.framework/functions/_shared/db.ts),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function dispatchTools(
   toolCalls: ToolCall[],
   ctx: CoreContext
 ): Promise<ToolResult[]> {
-  const results: ToolResult[] = []
-
-  for (const call of toolCalls) {
-    try {
-      // Lookup action for this tool
-      const { data: action, error } = await adminDb
-        .from('actions')
-        .select('*')
-        .eq('slug', call.tool)
-        .eq('is_active', true)
-        .single()
-
-      if (error || !action) {
-        results.push({
-          tool: call.tool,
-          id: call.id,
-          result: null,
-          error: `Tool "${call.tool}" not found`
-        })
-        continue
-      }
-
-      // Execute tool via pipeline-runner pattern
-      const result = await executeToolAction(action, call.params, ctx)
-
-      results.push({
-        tool: call.tool,
-        id: call.id,
-        result
-      })
-
-    } catch (error: any) {
-      results.push({
-        tool: call.tool,
-        id: call.id,
-        result: null,
-        error: error.message
-      })
-    }
-  }
-
-  return results
+  return withSpan(ctx, 'agent.dispatch_tools', async (ctx) => {
+    return Promise.all(toolCalls.map(async (call) => {
+      return withSpan(ctx, `agent.tool.${call.tool}`, async (ctx) => {
+        try {
+          // CIL tools are built into the runner and do not need an actions table row.
+          if (CIL_TOOL_SLUGS.has(call.tool)) {
+            const result = await executeToolAction({ handler: call.tool }, call.params, ctx)
+            return {
+              tool: call.tool,
+              id: call.id,
+              result
+            }
+          }
+          const { data: action, error } = await adminDb
+            .from('actions')
+            .select('*')
+            .eq('slug', call.tool)
+            .eq('is_active', true)
+            .single()
+          if (error || !action) {
+            return {
+              tool: call.tool,
+              id: call.id,
+              result: null,
+              error: `Tool "${call.tool}" not found`
+            }
+          }
+          const result = await executeToolAction(action, call.params, ctx)
+          return {
+            tool: call.tool,
+            id: call.id,
+            result
+          }
+        } catch (error: any) {
+          return {
+            tool: call.tool,
+            id: call.id,
+            result: null,
+            error: error.message
+          }
+        }
+      }, { onEnd: emitSpan })
+    }))
+  }, { onEnd: emitSpan })
 }
-
-/**
- * Dispatches a single tool action to its handler based on `action.handler`.
- *
- * Supported handlers (mirrors pipeline-runner stageHandlers):
- *   - `search_knowledge` → `executeSearchKnowledge`
- *   - `query_items` → `executeQueryItems`
- *   - `create_record` → `executeCreateRecord`
- *   - `update_item` → `executeUpdateItem`
- *   - `run_pipeline` → `runPipeline` (dynamic import to avoid circular deps)
- *   - `send_notification` → `executeSendNotification`
- *
- * @param action - Action record from the actions table
- * @param params - Tool call parameters (from LLM function_call.arguments)
- * @param ctx - CoreContext
- * @returns Promise<any> — handler output
- * @throws Error('Unknown tool handler') on unrecognised action.handler
- * @calledBy dispatchTools
- */
+// CIL[END chunk_id="agent-runner_dispatchtools_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_executetoolaction_1784488696" type="function" identity="executeToolAction" parent="none"]
+// CIL[DOC-MACRO purpose="Dispatch a single tool action to its handler"]
+// CIL[DOC-RESPONSIBILITY responsibility="Route action.handler to the correct tool handler implementation"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/src/components/ui/ItemListView.tsx,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/tests.ts,.framework/functions/_shared/index.ts,.framework/functions/auth.ts,custom/apps/cortex/functions/custom_cil-callmap.ts"]
+// CIL[DOC-CONTRACT inputs="action: any\nparams: any\nctx: CoreContext" outputs="handler output" errors="throws Unknown tool handler" side_effects="May dynamically import pipeline-runner and call handlers; calls CIL tool handlers"]
+// CIL[DOC-MICRO logic_summary="Dynamically imports pipeline-runner, switches on action.handler, and awaits the matching handler (including built-in CIL tools)" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: dispatchTools,executeAgentInference,runAgent. Direct callees: executeSearchKnowledge,executeSendNotification,imports(.framework/src/components/ui/ItemListView.tsx),executeUpdateItem,executeQueryItems,executeCreateRecord,params(.framework/src/components/runtime/DataDetailPage.tsx),handler(.framework/functions/tests.ts),pipeline(.framework/functions/_shared/index.ts),context(.framework/functions/auth.ts). Related files: .framework/src/components/ui/ItemListView.tsx,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/tests.ts,.framework/functions/_shared/index.ts,.framework/functions/auth.ts,custom/apps/cortex/functions/custom_cil-callmap.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: dispatchTools,executeAgentInference,runAgent. Total affected: 3." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [dispatchTools,executeAgentInference,runAgent] and callees [executeSearchKnowledge,executeSendNotification,imports(.framework/src/components/ui/ItemListView.tsx),executeUpdateItem,executeQueryItems,executeCreateRecord,params(.framework/src/components/runtime/DataDetailPage.tsx),handler(.framework/functions/tests.ts),pipeline(.framework/functions/_shared/index.ts),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function executeToolAction(
   action: any,
   params: any,
   ctx: CoreContext
 ): Promise<any> {
-  // Import pipeline-runner handlers dynamically to avoid circular deps
-  const { runPipeline } = await import('./pipeline-runner')
-
-  switch (action.handler) {
-    case 'search_knowledge':
-      return await executeSearchKnowledge(params, ctx)
-    
-    case 'query_items':
-      return await executeQueryItems(params, ctx)
-    
-    case 'create_record':
-      return await executeCreateRecord(params, ctx)
-    
-    case 'update_item':
-      return await executeUpdateItem(params, ctx)
-    
-    case 'run_pipeline':
-      const result = await runPipeline(params.pipeline_id, params.trigger_data || {}, ctx)
-      return { success: result.status === 'completed', result }
-    
-    case 'send_notification':
-      return await executeSendNotification(params, ctx)
-    
-    default:
-      throw new Error(`Unknown tool handler: ${action.handler}`)
-  }
+  return withSpan(ctx, `agent.tool_action.${action.handler || 'unknown'}`, async (ctx) => {
+    const { runPipeline } = await import('./pipeline-runner')
+    switch (action.handler) {
+      case 'search_knowledge':
+        return await executeSearchKnowledge(params, ctx)
+      case 'query_items':
+        return await executeQueryItems(params, ctx)
+      case 'create_record':
+        return await executeCreateRecord(params, ctx)
+      case 'update_item':
+        return await executeUpdateItem(params, ctx)
+      case 'run_pipeline':
+        const result = await runPipeline(params.pipeline_id, params.trigger_data || {}, ctx)
+        return { success: result.status === 'completed', result }
+      case 'send_notification':
+        return await executeSendNotification(params, ctx)
+      case 'cil_chunk_lookup':
+        return await executeCilChunkLookup(params, ctx)
+      case 'cil_get_contract':
+        return await executeCilGetContract(params, ctx)
+      case 'cil_blast_radius':
+        return await executeCilBlastRadius(params, ctx)
+      case 'cil_hash_validate':
+        return await executeCilHashValidate(params, ctx)
+      case 'cil_project_status':
+        return await executeCilProjectStatus(params, ctx)
+      case 'search_logs':
+        return await executeSearchLogs(params, ctx)
+      case 'search_observability':
+        return await executeSearchObservability(params, ctx)
+      default:
+        throw new Error(`Unknown tool handler: ${action.handler}`)
+    }
+  }, { onEnd: emitSpan })
 }
-
-// ─── TOOL HANDLERS ────────────────────────────────────────────────────────────
-
-/**
- * Tool: search_knowledge — vector similarity search via `search_similar_embeddings`
- * RPC, falling back to text search on error.
- *
- * @param params.query: string — search query text
- * @param params.embedding: number[] | undefined — pre-computed embedding vector
- * @param params.limit: number (default 5)
- * @param params.threshold: number (default 0.7)
- * @returns { results[], method: 'vector'|'text_fallback' }
- * @throws never — falls back to text search on RPC failure
- * @sideEffects DB: search_similar_embeddings RPC or embeddings text search
- */
+// CIL[END chunk_id="agent-runner_executetoolaction_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_executesearchknowledge_1784488696" type="function" identity="executeSearchKnowledge" parent="none"]
+// CIL[DOC-MACRO purpose="Tool handler: search_knowledge via vector similarity"]
+// CIL[DOC-RESPONSIBILITY responsibility="Run search_similar_embeddings and fall back to text search"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/migrations/001_schema.sql,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/_shared/db.ts,.framework/functions/tests.ts,.framework/functions/auth.ts"]
+// CIL[DOC-CONTRACT inputs="params: any\nctx: CoreContext" outputs="{ results, method }" errors="returns text_fallback results on RPC failure" side_effects="DB RPC or text search on embeddings table"]
+// CIL[DOC-MICRO logic_summary="Calls search_similar_embeddings with account scoping; on error runs textSearch on embeddings.content" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: executeToolAction,dispatchTools,executeAgentInference. Direct callees: embeddings(.framework/migrations/001_schema.sql),params(.framework/src/components/runtime/DataDetailPage.tsx),adminDb(.framework/functions/_shared/db.ts),handler(.framework/functions/tests.ts),context(.framework/functions/auth.ts). Related files: .framework/migrations/001_schema.sql,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/_shared/db.ts,.framework/functions/tests.ts,.framework/functions/auth.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: executeToolAction,dispatchTools,executeAgentInference. Total affected: 3." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [executeToolAction,dispatchTools,executeAgentInference] and callees [embeddings(.framework/migrations/001_schema.sql),params(.framework/src/components/runtime/DataDetailPage.tsx),adminDb(.framework/functions/_shared/db.ts),handler(.framework/functions/tests.ts),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function executeSearchKnowledge(
   params: any,
   ctx: CoreContext
 ): Promise<any> {
   const { query, knowledge_sources, limit = 5 } = params
-
   const { data: results, error } = await adminDb.rpc('search_similar_embeddings', {
     p_account_id: ctx.accountId,
     p_model_id: params.model_id || 'text-embedding-ada-002',
-    p_query_embedding: params.embedding, // If pre-computed
+    p_query_embedding: params.embedding, 
     p_limit: limit,
     p_threshold: params.threshold || 0.7
   })
-
   if (error) {
-    // Fallback to text search
     const { data: fallback } = await adminDb
       .from('embeddings')
       .select('*')
       .eq('account_id', ctx.accountId)
       .textSearch('content', query)
       .limit(limit)
-    
     return { results: fallback || [], method: 'text_fallback' }
   }
-
   return { results: results || [], method: 'vector' }
 }
-
-/**
- * Tool: query_items — filtered SELECT on any table scoped to ctx.accountId.
- *
- * @param params.entity: string — table name
- * @param params.filters: Record<string, any> (default {})
- * @param params.limit: number (default 10)
- * @returns { items[] }
- * @throws Error on DB failure
- * @sideEffects DB read: params.entity table
- */
+// CIL[END chunk_id="agent-runner_executesearchknowledge_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_executequeryitems_1784488696" type="function" identity="executeQueryItems" parent="none"]
+// CIL[DOC-MACRO purpose="Tool handler: query_items filtered SELECT"]
+// CIL[DOC-RESPONSIBILITY responsibility="Run an account-scoped, filtered SELECT on a specified table"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files="custom/apps/cortex/functions/custom_kb-chunker-test.ts,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/_shared/db.ts,.framework/functions/tests.ts,.framework/functions/auth.ts"]
+// CIL[DOC-CONTRACT inputs="params: any\nctx: CoreContext" outputs="{ items }" errors="throws on DB failure" side_effects="DB read of params.entity table"]
+// CIL[DOC-MICRO logic_summary="Builds adminDb query with account filter and optional key-value filters, then returns rows" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: executeToolAction,dispatchTools,executeAgentInference. Direct callees: failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts),params(.framework/src/components/runtime/DataDetailPage.tsx),adminDb(.framework/functions/_shared/db.ts),handler(.framework/functions/tests.ts),context(.framework/functions/auth.ts). Related files: custom/apps/cortex/functions/custom_kb-chunker-test.ts,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/_shared/db.ts,.framework/functions/tests.ts,.framework/functions/auth.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: executeToolAction,dispatchTools,executeAgentInference. Total affected: 3." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [executeToolAction,dispatchTools,executeAgentInference] and callees [failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts),params(.framework/src/components/runtime/DataDetailPage.tsx),adminDb(.framework/functions/_shared/db.ts),handler(.framework/functions/tests.ts),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function executeQueryItems(
   params: any,
   ctx: CoreContext
 ): Promise<any> {
   const { entity, filters = {}, limit = 10 } = params
-
   let query = adminDb
     .from(entity)
     .select('*')
     .eq('account_id', ctx.accountId)
     .limit(limit)
-
-  // Apply filters
   Object.entries(filters).forEach(([key, value]) => {
     query = query.eq(key, value)
   })
-
   const { data, error } = await query
-
   if (error) throw new Error(`Query failed: ${error.message}`)
   return { items: data || [] }
 }
-
-/**
- * Tool: create_record — inserts a record into any table.
- *
- * @param params.entity: string — table name
- * @param params.data: Record<string, any> — field values
- * @returns { record } — the inserted row
- * @throws Error on DB failure
- * @sideEffects DB write: params.entity table
- */
+// CIL[END chunk_id="agent-runner_executequeryitems_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_executecreaterecord_1784488696" type="function" identity="executeCreateRecord" parent="none"]
+// CIL[DOC-MACRO purpose="Tool handler: create_record insert"]
+// CIL[DOC-RESPONSIBILITY responsibility="Insert a record into any table, stamping account_id and audit fields"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/_shared/db.ts,.framework/functions/tests.ts,custom/apps/cortex/functions/custom_kb-chunker-test.ts,.framework/functions/auth.ts,.framework/functions/admin-data.ts,.framework/functions/types.ts"]
+// CIL[DOC-CONTRACT inputs="params: any\nctx: CoreContext" outputs="{ record }" errors="throws on DB failure" side_effects="DB write to params.entity table"]
+// CIL[DOC-MICRO logic_summary="Inserts data with account_id, created_by and timestamps, then selects single row" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: executeToolAction,dispatchTools,executeAgentInference. Direct callees: params(.framework/src/components/runtime/DataDetailPage.tsx),adminDb(.framework/functions/_shared/db.ts),handler(.framework/functions/tests.ts),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts),context(.framework/functions/auth.ts). Related files: .framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/_shared/db.ts,.framework/functions/tests.ts,custom/apps/cortex/functions/custom_kb-chunker-test.ts,.framework/functions/auth.ts,.framework/functions/admin-data.ts,.framework/functions/types.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: executeToolAction,dispatchTools,executeAgentInference. Total affected: 3." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [executeToolAction,dispatchTools,executeAgentInference] and callees [params(.framework/src/components/runtime/DataDetailPage.tsx),adminDb(.framework/functions/_shared/db.ts),handler(.framework/functions/tests.ts),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function executeCreateRecord(
   params: any,
   ctx: CoreContext
 ): Promise<any> {
   const { entity, data } = params
-
   const { data: result, error } = await adminDb
     .from(entity)
     .insert({
@@ -1088,27 +611,29 @@ async function executeCreateRecord(
     })
     .select()
     .single()
-
   if (error) throw new Error(`Create failed: ${error.message}`)
   return { record: result }
 }
-
-/**
- * Tool: update_item — updates a record by ID in any table.
- *
- * @param params.entity: string — table name
- * @param params.record_id: string — UUID of the record
- * @param params.data: Record<string, any> — fields to update
- * @returns { record } — the updated row
- * @throws Error on DB failure
- * @sideEffects DB write: params.entity table
- */
+// CIL[END chunk_id="agent-runner_executecreaterecord_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_executeupdateitem_1784488696" type="function" identity="executeUpdateItem" parent="none"]
+// CIL[DOC-MACRO purpose="Tool handler: update_item by ID"]
+// CIL[DOC-RESPONSIBILITY responsibility="Update a record by ID, stamping updated_at and updated_by"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/functions/timers.ts,.framework/functions/_shared/db.ts,.framework/functions/tests.ts,custom/apps/cortex/functions/custom_kb-chunker-test.ts,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/auth.ts"]
+// CIL[DOC-CONTRACT inputs="params: any\nctx: CoreContext" outputs="{ record }" errors="throws on DB failure" side_effects="DB write to params.entity table"]
+// CIL[DOC-MICRO logic_summary="Updates by id with merged data, updated_at, updated_by, and returns single row" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: executeToolAction,dispatchTools,executeAgentInference. Direct callees: update(.framework/functions/timers.ts),adminDb(.framework/functions/_shared/db.ts),handler(.framework/functions/tests.ts),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts),params(.framework/src/components/runtime/DataDetailPage.tsx),context(.framework/functions/auth.ts). Related files: .framework/functions/timers.ts,.framework/functions/_shared/db.ts,.framework/functions/tests.ts,custom/apps/cortex/functions/custom_kb-chunker-test.ts,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/auth.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: executeToolAction,dispatchTools,executeAgentInference. Total affected: 3." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [executeToolAction,dispatchTools,executeAgentInference] and callees [update(.framework/functions/timers.ts),adminDb(.framework/functions/_shared/db.ts),handler(.framework/functions/tests.ts),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts),params(.framework/src/components/runtime/DataDetailPage.tsx),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function executeUpdateItem(
   params: any,
   ctx: CoreContext
 ): Promise<any> {
   const { entity, record_id, data } = params
-
   const { data: result, error } = await adminDb
     .from(entity)
     .update({
@@ -1119,28 +644,29 @@ async function executeUpdateItem(
     .eq('id', record_id)
     .select()
     .single()
-
   if (error) throw new Error(`Update failed: ${error.message}`)
   return { record: result }
 }
-
-/**
- * Tool: send_notification — inserts rows into the `watchers` table.
- *
- * @param params.message: string — notification text
- * @param params.recipients: string[] — person UUIDs to notify
- * @param params.entity_type: string | undefined
- * @param params.entity_id: string | undefined
- * @returns { notified_count }
- * @throws Error on DB failure
- * @sideEffects DB write: watchers table
- */
+// CIL[END chunk_id="agent-runner_executeupdateitem_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_executesendnotification_1784488696" type="function" identity="executeSendNotification" parent="none"]
+// CIL[DOC-MACRO purpose="Tool handler: send_notification inserts watchers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create watcher rows for each recipient"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/migrations/001_schema.sql,.framework/functions/tests.ts,custom/apps/cortex/functions/custom_kb-chunker-test.ts,.framework/functions/_shared/db.ts,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/auth.ts"]
+// CIL[DOC-CONTRACT inputs="params: any\nctx: CoreContext" outputs="{ notified_count }" errors="throws on DB failure" side_effects="DB write watchers table"]
+// CIL[DOC-MICRO logic_summary="Maps recipients to watcher rows and inserts batch, returning count" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: executeToolAction,dispatchTools,executeAgentInference. Direct callees: watchers(.framework/migrations/001_schema.sql),handler(.framework/functions/tests.ts),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts),adminDb(.framework/functions/_shared/db.ts),params(.framework/src/components/runtime/DataDetailPage.tsx),context(.framework/functions/auth.ts). Related files: .framework/migrations/001_schema.sql,.framework/functions/tests.ts,custom/apps/cortex/functions/custom_kb-chunker-test.ts,.framework/functions/_shared/db.ts,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/auth.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: executeToolAction,dispatchTools,executeAgentInference. Total affected: 3." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [executeToolAction,dispatchTools,executeAgentInference] and callees [watchers(.framework/migrations/001_schema.sql),handler(.framework/functions/tests.ts),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts),adminDb(.framework/functions/_shared/db.ts),params(.framework/src/components/runtime/DataDetailPage.tsx),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function executeSendNotification(
   params: any,
   ctx: CoreContext
 ): Promise<any> {
   const { message, recipients = [], entity_type, entity_id } = params
-
   const notifications = recipients.map((recipientId: string) => ({
     account_id: ctx.accountId,
     person_id: recipientId,
@@ -1150,59 +676,48 @@ async function executeSendNotification(
     is_read: false,
     created_at: new Date().toISOString()
   }))
-
   if (notifications.length > 0) {
     const { error } = await adminDb.from('watchers').insert(notifications)
     if (error) throw new Error(`Notification failed: ${error.message}`)
   }
-
   return { notified_count: notifications.length }
 }
-
-// ─── ESCALATION ────────────────────────────────────────────────────────────
-
-/**
- * Handles confidence-based escalation when inference confidence falls below
- * `promptConfig.confidence_threshold`.
- *
- * Actions taken:
- *   1. Attempt to set `threads.data.escalation_status = 'pending'` (via jsonb_set RPC)
- *   2. Emit `agent.inference.low_confidence` audit log
- *   3. If `promptConfig.escalation_action === 'pipeline'` and
- *      `promptConfig.escalation_target` is set, run the escalation pipeline
- *      via dynamic import of `runPipeline`
- *
- * @param threadId - UUID of the thread being escalated
- * @param confidence - The confidence score that triggered escalation
- * @param promptConfig - Prompt config with escalation settings
- * @param ctx - CoreContext
- * @returns Promise<void> — always resolves
- * @throws never — DB errors are silently dropped (best-effort)
- * @sideEffects DB write: threads.data (jsonb_set for escalation_status)
- * @sideEffects DB write: emitAudit (agent.inference.low_confidence)
- * @sideEffects Calls runPipeline (if escalation_action === 'pipeline')
- * @calledBy runAgent (when agentResponse.confidence < threshold)
- */
+// CIL[END chunk_id="agent-runner_executesendnotification_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_handleescalation_1784488696" type="function" identity="handleEscalation" parent="none"]
+// CIL[DOC-MACRO purpose="Handle low-confidence escalation for a thread"]
+// CIL[DOC-RESPONSIBILITY responsibility="Mark thread as pending escalation, set target item to human_assigned, emit audit, and run escalation pipeline if configured"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/functions/_shared/index.ts,.framework/functions/_shared/db.ts,.framework/functions/timers.ts,.framework/functions/auth.ts,.framework/docs/runtime-types.md,.framework/migrations/001_schema.sql"]
+// CIL[DOC-CONTRACT inputs="threadId: string\nconfidence: number\npromptConfig: any\nctx: CoreContext" outputs="void" errors="none; DB and pipeline failures are logged, not thrown" side_effects="DB writes threads/items/audit; may call runPipeline"]
+// CIL[DOC-MICRO logic_summary="Updates thread.data.escalation_status, sets item status to human_assigned, emits low_confidence audit, and conditionally runs escalation_target pipeline (resolving slug to UUID and swallowing pipeline errors)" notable_decisions="[]"]
+// CIL[DOC-LEARNING topic="agent-runner:escalation_pipeline_lookup" content="The pipelines table has a 'slug' column used as the human-readable pipeline identifier. handleEscalation resolves escalation_target (which may be a slug or name) by querying on slug or name and then merges the resolved pipeline_id into thread.data for subsequent runs."]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: runAgent. Direct callees: pipeline(.framework/functions/_shared/index.ts),adminDb(.framework/functions/_shared/db.ts),update(.framework/functions/timers.ts),context(.framework/functions/auth.ts). Related files: .framework/functions/_shared/index.ts,.framework/functions/_shared/db.ts,.framework/functions/timers.ts,.framework/functions/auth.ts,.framework/docs/runtime-types.md,.framework/migrations/001_schema.sql." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: runAgent. Total affected: 1." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [runAgent] and callees [pipeline(.framework/functions/_shared/index.ts),adminDb(.framework/functions/_shared/db.ts),update(.framework/functions/timers.ts),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function handleEscalation(
   threadId: string,
   confidence: number,
   promptConfig: any,
   ctx: CoreContext
 ): Promise<void> {
-  // Update thread escalation status
+  return withSpan(ctx, 'agent.escalation', async (ctx) => {
+  const { data: currentThread } = await adminDb
+    .from('threads')
+    .select('data')
+    .eq('id', threadId)
+    .single()
   await adminDb
     .from('threads')
     .update({
-      data: adminDb.rpc('jsonb_set', {
-        target: adminDb.from('threads').select('data').eq('id', threadId).single(),
-        path: '{escalation_status}',
-        new_value: '"pending"'
-      })
+      data: {
+        ...(currentThread?.data || {}),
+        escalation_status: 'pending'
+      }
     })
     .eq('id', threadId)
-
-  // If the thread targets an item (e.g., a support ticket), mark that item as
-  // human-assigned so it shows up in the human queue and stops AI responses.
   const { data: thread } = await adminDb
     .from('threads')
     .select('target_type, target_id')
@@ -1228,8 +743,6 @@ async function handleEscalation(
         .eq('id', thread.target_id)
     }
   }
-
-  // Fire trigger event
   await emitAudit(ctx, 'agent.inference.low_confidence', {
     type: 'thread',
     id: threadId,
@@ -1240,84 +753,906 @@ async function handleEscalation(
     escalation_action: promptConfig.escalation_action,
     escalation_target: promptConfig.escalation_target
   })
-
-  // If escalation pipeline configured, run it
   if (promptConfig.escalation_action === 'pipeline' && promptConfig.escalation_target) {
     const { runPipeline } = await import('./pipeline-runner')
-    await runPipeline(
-      promptConfig.escalation_target,
-      {
-        thread_id: threadId,
-        confidence,
-        threshold: promptConfig.confidence_threshold,
-        reason: 'low_confidence'
-      },
-      ctx
-    )
-  }
-}
+    let pipelineId = promptConfig.escalation_target
+
+    // escalation_target is usually stored as a slug/name (e.g. "support_escalation"),
+    // but runPipeline expects a UUID. Resolve the slug if needed.
+    const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+    if (!isUuid.test(pipelineId)) {
+      const { data: pipeline, error: pipelineLookupError } = await adminDb
+        .from('pipelines')
+        .select('id')
+        .or(`slug.eq.${pipelineId},name.eq.${pipelineId}`)
+        .eq('is_active', true)
+        .maybeSingle()
 
-// ─── MESSAGE PERSISTENCE ───────────────────────────────────────────────────────────
+      if (pipelineLookupError) {
+        console.warn(`Escalation pipeline lookup failed for '${pipelineId}': ${pipelineLookupError.message}`)
+        return
+      }
+      if (!pipeline) {
+        console.warn(`Escalation pipeline not found: ${pipelineId}`)
+        return
+      }
+      pipelineId = pipeline.id
+    }
 
-/**
- * Inserts a message row into the `messages` table for a thread.
- *
- * For human messages: `person_id` is set to `ctx.principal.id`.
- * For agent/system/tool messages: `person_id` is null.
- * The `data` JSONB field carries `message_type` and any additional metadata.
- *
- * @param threadId - UUID of the parent thread
- * @param content - Message text content
- * @param messageType - Role classifier for the message
- * @param data - Additional JSONB metadata (e.g. confidence, tool_calls, agent_id)
- * @param ctx - CoreContext with accountId and principal
- * @returns Promise<any> — the inserted messages row
- * @throws Error('Failed to save message') on DB insert failure
- * @inputSpec messageType: 'human'|'agent'|'system'|'tool_call'|'tool_result'
- * @sideEffects DB write: messages table
- * @calledBy runAgent (user message + agent response)
- */
-// Map a thread type slug to the corresponding message/reply type slug.
+    try {
+      await runPipeline(
+        pipelineId,
+        {
+          thread_id: threadId,
+          confidence,
+          threshold: promptConfig.confidence_threshold,
+          reason: 'low_confidence'
+        },
+        ctx
+      )
+    } catch (err: any) {
+      console.warn(`Escalation pipeline '${promptConfig.escalation_target}' failed: ${err.message}`)
+    }
+  }
+}, { onEnd: emitSpan })
+}
+// CIL[END chunk_id="agent-runner_handleescalation_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_getreplytypeslug_1784488696" type="function" identity="getReplyTypeSlug" parent="none"]
+// CIL[DOC-MACRO purpose="Map a thread type slug to its reply message type slug"]
+// CIL[DOC-RESPONSIBILITY responsibility="Resolve support/community reply type slugs for message persistence"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/functions/system.ts,.framework/functions/auth.ts,.framework/functions/types.ts,.framework/functions/_shared/resolve-ids.ts"]
+// CIL[DOC-CONTRACT inputs="threadTypeSlug: string" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Returns support_reply or community_reply for matching thread types, otherwise message" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: runAgent. Direct callees: types(.framework/functions/system.ts),context(.framework/functions/auth.ts). Related files: .framework/functions/system.ts,.framework/functions/auth.ts,.framework/functions/types.ts,.framework/functions/_shared/resolve-ids.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: runAgent. Total affected: 1." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [runAgent] and callees [types(.framework/functions/system.ts),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="semantic" content="Maps thread type slugs to reply message type slugs. engineering ticket threads (eng_ticket_thread) produce eng_ticket_comment replies, support threads produce support_reply, community threads produce community_reply, and all other thread types fall back to message." status="ready"]
 function getReplyTypeSlug(threadTypeSlug: string): string {
   if (threadTypeSlug === 'support_thread') return 'support_reply'
   if (threadTypeSlug === 'community_thread') return 'community_reply'
+  if (threadTypeSlug === 'eng_ticket_thread') return 'eng_ticket_comment'
   return 'message'
 }
-
+// CIL[END chunk_id="agent-runner_getreplytypeslug_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_savemessage_1784488696" type="function" identity="saveMessage" parent="none"]
+// CIL[DOC-MACRO purpose="Persist a message row in the messages table"]
+// CIL[DOC-RESPONSIBILITY responsibility="Insert a human, agent, system, or tool message with sequence, direction, visibility, and metadata"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/functions/_shared/db.ts,.framework/functions/auth.ts,.framework/migrations/001_schema.sql,.framework/functions/ai-interactions.ts,.framework/docs/runtime-types.md"]
+// CIL[DOC-CONTRACT inputs="threadId: string\ncontent: string\nmessageType: string\ndata: any\nctx: CoreContext\nmessageTypeSlug: string\nvisibility?: string" outputs="message row" errors="throws if insert fails" side_effects="DB write messages table via createRecord"]
+// CIL[DOC-MICRO logic_summary="Computes next sequence, direction, visibility, and calls createRecord with type_slug and data payload" notable_decisions=["Message visibility is inherited from the parent thread so an internal Solution AI workbench never accidentally produces public customer messages."]
+// CIL[DOC-LEARNING topic="agent-runner:messages_schema" content="The messages table has no 'sender' column. Message provenance is captured via person_id for human messages and encoded in messageType/data for agent/system/tool messages. Inserting a 'sender' column fails with a 42703 error."]
+// CIL[DOC-LEARNING topic="agent-runner:message_visibility" content="message visibility must be derived from thread.visibility, not from messageType. Agent messages in a private support AI thread should be internal; the same code path running on the public customer thread must remain external. Pass thread.visibility into saveMessage explicitly."]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: runAgent. Direct callees: adminDb(.framework/functions/_shared/db.ts),context(.framework/functions/auth.ts). Related files: .framework/functions/_shared/db.ts,.framework/functions/auth.ts,.framework/migrations/001_schema.sql,.framework/functions/ai-interactions.ts,.framework/docs/runtime-types.md." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: runAgent. Total affected: 1." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [runAgent] and callees [adminDb(.framework/functions/_shared/db.ts),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function saveMessage(
   threadId: string,
   content: string,
   messageType: 'human' | 'agent' | 'system' | 'tool_call' | 'tool_result',
   data: any,
   ctx: CoreContext,
-  messageTypeSlug: string = 'message'
+  messageTypeSlug: string = 'message',
+  visibility?: string
 ): Promise<any> {
-  const { count } = await adminDb
-    .from('messages')
-    .select('id', { count: 'exact', head: true })
-    .eq('thread_id', threadId)
-  const sequence = (count ?? 0) + 1
-  const direction = messageType === 'human' ? 'inbound' : 'outbound'
-  // human + agent messages are customer-visible; tool/system messages are internal
-  const visibility = (messageType === 'human' || messageType === 'agent') ? 'external' : 'internal'
+  return withSpan(ctx, 'agent.save_message', async (ctx) => {
+    const { count } = await adminDb
+      .from('messages')
+      .select('id', { count: 'exact', head: true })
+      .eq('thread_id', threadId)
+    const sequence = (count ?? 0) + 1
+    const direction = messageType === 'human' ? 'inbound' : 'outbound'
+    const resolvedVisibility = visibility || ((messageType === 'human' || messageType === 'agent') ? 'external' : 'internal')
+    const message = await createRecord(ctx, {
+      entity: 'messages',
+      type_slug: messageTypeSlug,
+      thread_id: threadId,
+      person_id: messageType === 'human' ? ctx.principal?.id : null,
+      content,
+      direction,
+      sequence,
+      visibility: resolvedVisibility,
+      data: {
+        message_type: messageType,
+        ...data
+      },
+    })
+    if (!message?.id) throw new Error('Failed to save message')
+    return message
+  }, { onEnd: emitSpan })
+}
+// CIL[END chunk_id="agent-runner_savemessage_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_exports_1784488696" type="interface" identity="exports" parent="none"]
+// CIL[DOC-MACRO purpose="Exported type contracts for agent runner"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define AgentConfig, InferenceResult, ToolCall, and ToolResult shapes"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/functions/integration-routes.ts,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/auth.ts,.framework/docs/runtime-types.md"]
+// CIL[DOC-CONTRACT inputs="none" outputs="TypeScript interfaces" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declares configuration, result, tool call, and tool result structures used across the module" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: none. Direct callees: interfaces(.framework/functions/integration-routes.ts),params(.framework/src/components/runtime/DataDetailPage.tsx),context(.framework/functions/auth.ts). Related files: .framework/functions/integration-routes.ts,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/auth.ts,.framework/docs/runtime-types.md." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: none. Total affected: 0." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [none] and callees [interfaces(.framework/functions/integration-routes.ts),params(.framework/src/components/runtime/DataDetailPage.tsx),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+export interface AgentConfig {
+  agent: any
+  promptConfig: any
+  thread: any
+  threadType: any
+}
+
+export interface InferenceResult {
+  content: string
+  confidence: number
+  tool_calls?: ToolCall[]
+  metadata?: Record<string, any>
+}
 
-  // Use admin-data's create() so type_slug is resolved server-side and
-  // design_schema + validation_schema are stamped from the type record.
-  const message = await createRecord(ctx, {
-    entity: 'messages',
-    type_slug: messageTypeSlug,
-    thread_id: threadId,
-    person_id: messageType === 'human' ? ctx.principal?.id : null,
-    content,
-    direction,
-    sequence,
-    visibility,
-    data: {
-      message_type: messageType,
-      ...data
+export interface ToolCall {
+  tool: string
+  params: Record<string, any>
+  id: string
+}
+
+export interface ToolResult {
+  tool: string
+  result: any
+  error?: string
+  id: string
+}
+// CIL[END chunk_id="agent-runner_exports_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_ciltools_1784488696" type="constant" identity="ciltools" parent="none"]
+// CIL[DOC-MACRO purpose="CIL tool definitions and helper utilities for the agent runner"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define OpenAI-style function tool schemas for CIL retrieval and provide normalise/compute helpers"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files="custom/apps/cortex/functions/custom_cil-agent.ts,custom/apps/cortex/functions/custom_cil-callmap.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="CIL_TOOLS constant and helper functions" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines CIL tool schemas; exposes normaliseCilChunkContent and computeCilChunkHash to validate stored chunk hashes" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: resolveAgentConfig,dispatchTools,executeToolAction. Direct callees: adminDb(.framework/functions/_shared/db.ts). Related files: custom/apps/cortex/functions/custom_cil-agent.ts,custom/apps/cortex/functions/custom_cil-callmap.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: resolveAgentConfig,dispatchTools,executeToolAction. Total affected: 3." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: thread.data.cil_config.use_cil_tools. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [resolveAgentConfig,dispatchTools,executeToolAction] and callees [adminDb(.framework/functions/_shared/db.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+const CIL_TOOLS: any[] = [
+  {
+    name: 'cil_chunk_lookup',
+    description: 'Search for a CIL chunk by name, file path, or purpose. Returns chunk_id, chunk_name, file_path, and macro.',
+    parameters: {
+      type: 'object',
+      properties: {
+        q: { type: 'string', description: 'Search term' },
+        project_id: { type: 'string', description: 'Optional project UUID to scope the search' },
+        limit: { type: 'number', description: 'Max results to return (default 5)' },
+      },
+      required: ['q'],
     },
+  },
+  {
+    name: 'cil_get_contract',
+    description: 'Get the full contract and metadata for a specific CIL chunk by its UUID.',
+    parameters: {
+      type: 'object',
+      properties: {
+        chunk_id: { type: 'string', description: 'UUID of the cil_chunk item' },
+      },
+      required: ['chunk_id'],
+    },
+  },
+  {
+    name: 'cil_blast_radius',
+    description: 'Find all chunks that transitively call or are called by a given chunk (imports, calls, exports, tested_by). Use before refactoring.',
+    parameters: {
+      type: 'object',
+      properties: {
+        chunk_id: { type: 'string', description: 'UUID of the chunk to check callers/callees for' },
+        max_depth: { type: 'number', description: 'Maximum BFS hop depth (default 3, max 6)' },
+      },
+      required: ['chunk_id'],
+    },
+  },
+  {
+    name: 'cil_hash_validate',
+    description: 'Check whether a CIL chunk\'s stored hash is current or has drifted (code was changed without updating CIL).',
+    parameters: {
+      type: 'object',
+      properties: {
+        chunk_id: { type: 'string', description: 'UUID of the chunk to validate' },
+      },
+      required: ['chunk_id'],
+    },
+  },
+  {
+    name: 'cil_project_status',
+    description: 'Get the full CIL pipeline status for a project: file count, chunk count, embedding coverage, and doc coverage.',
+    parameters: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'string', description: 'UUID of the cil_project' },
+      },
+      required: ['project_id'],
+    },
+  },
+]
+
+const CIL_TOOL_SLUGS = new Set(CIL_TOOLS.map(t => t.name))
+
+function normaliseCilChunkContent(raw: string): string {
+  const lines = raw.replace(/\r\n/g, '\n').split('\n')
+  const filtered = lines.filter(line => {
+    const trimmed = line.trim()
+    return !trimmed.match(/^(?:(?:\/\/|--|#)\s*|<!--\s*)CIL\[(BEGIN|END)/) &&
+           !trimmed.match(/^(?:(?:\/\/|--|#)\s*|<!--\s*)CIL\[DOC-/)
   })
+  return filtered.join('\n').trim()
+}
+
+function computeCilChunkHash(content: string): string {
+  return createHash('sha256').update(normaliseCilChunkContent(content), 'utf8').digest('hex').slice(0, 16)
+}
+
+// CIL[END chunk_id="agent-runner_ciltools_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_runagent_1784488696" type="function" identity="runAgent" parent="none"]
+// CIL[DOC-MACRO purpose="Execute an AI agent conversation turn"]
+// CIL[DOC-RESPONSIBILITY responsibility="Orchestrate resolve, save user message, run inference, escalate if needed, save response, and audit"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/migrations/001_schema.sql,custom/apps/cortex/functions/custom_kb-chunker-test.ts,.framework/functions/_shared/index.ts,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/auth.ts,.framework/functions/ai-agents.ts,.framework/cli/commands/agents.ts"]
+// CIL[DOC-CONTRACT inputs="threadId: string\nuserMessage: string\nctx: CoreContext" outputs="agent message row" errors="throws on resolve or inference failure" side_effects="DB reads/writes, audit logs, possible escalation pipeline"]
+// CIL[DOC-MICRO logic_summary="Resolves config, saves user message, executes agent inference, escalates low confidence, saves response with sources, and emits audit" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: none. Direct callees: executeAgentInference,getReplyTypeSlug,logs(.framework/migrations/001_schema.sql),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts),saveMessage,pipeline(.framework/functions/_shared/index.ts),resolveAgentConfig,handleEscalation,title(.framework/src/components/runtime/DataDetailPage.tsx),context(.framework/functions/auth.ts). Related files: .framework/migrations/001_schema.sql,custom/apps/cortex/functions/custom_kb-chunker-test.ts,.framework/functions/_shared/index.ts,.framework/src/components/runtime/DataDetailPage.tsx,.framework/functions/auth.ts,.framework/functions/ai-agents.ts,.framework/cli/commands/agents.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: none. Total affected: 0." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [none] and callees [executeAgentInference,getReplyTypeSlug,logs(.framework/migrations/001_schema.sql),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts),saveMessage,pipeline(.framework/functions/_shared/index.ts),resolveAgentConfig,handleEscalation,title(.framework/src/components/runtime/DataDetailPage.tsx),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+export async function runAgent(
+  threadId: string,
+  userMessage: string,
+  ctx: CoreContext
+): Promise<any> {
+  return withSpan(ctx, 'agent.runAgent', async (ctx) => {
+    const startTime = Date.now()
+    try {
+      const config = await resolveAgentConfig(threadId, ctx)
+      if (!config) {
+        throw new Error(`Could not resolve agent configuration for thread ${threadId}`)
+      }
+      const { agent, promptConfig, thread, threadType } = config
+      const replyTypeSlug = getReplyTypeSlug(threadType?.slug)
+      const threadVisibility = thread?.visibility || 'external'
+      const userMsg = await saveMessage(threadId, userMessage, 'human', null, ctx, replyTypeSlug, threadVisibility)
+      const maxToolIterations = promptConfig.metadata?.max_tool_iterations ?? 5
+      const agentResponse = await executeAgentInference(
+        config,
+        userMessage,
+        ctx,
+        maxToolIterations
+      )
+      const isEscalated = agentResponse.confidence < (promptConfig.confidence_threshold || 0)
+      if (isEscalated) {
+        await handleEscalation(
+          threadId,
+          agentResponse.confidence,
+          promptConfig,
+          ctx
+        )
+      }
+      const agentMsg = await saveMessage(
+        threadId,
+        agentResponse.content,
+        'agent',
+        {
+          confidence: agentResponse.confidence,
+          retrieval_confidence: agentResponse.retrievalConfidence,
+          retrieved_sources: (agentResponse.retrievedSources || []).map((s: any) => ({
+            document_id: s.document_id,
+            title: s.title,
+            similarity: s.similarity,
+            item_type: s.item_type,
+            vector_type: s.vector_type,
+          })),
+          tool_calls: agentResponse.tool_calls,
+          agent_id: agent.id,
+          prompt_config_id: promptConfig.id,
+          sender_type: 'agent',
+          escalated: isEscalated,
+        },
+        ctx,
+        replyTypeSlug,
+        threadVisibility
+      )
+      await emitAudit(ctx, 'agent.inference.completed', {
+        type: 'agent_message',
+        id: agentMsg.id,
+        account_id: ctx.accountId ?? undefined
+      }, {
+        thread_id: threadId,
+        agent_id: agent.id,
+        confidence: agentResponse.confidence,
+        retrieval_confidence: agentResponse.retrievalConfidence,
+        sources_count: agentResponse.retrievedSources?.length || 0,
+        has_tool_calls: !!agentResponse.tool_calls?.length,
+        duration_ms: Date.now() - startTime
+      })
+      await emitOutcome(ctx, 'agent.outcome', 'success', {
+        thread_id: threadId,
+        agent_id: agent.id,
+        confidence: agentResponse.confidence,
+        escalated: isEscalated
+      })
+      return agentMsg
+    } catch (error: any) {
+      await emitAudit(ctx, 'agent.inference.failed', {
+        type: 'agent_message',
+        id: 'failed',
+        account_id: ctx.accountId ?? undefined
+      }, {
+        thread_id: threadId,
+        error: error.message
+      })
+      await emitOutcome(ctx, 'agent.outcome', 'failure', {
+        thread_id: threadId,
+        error: error.message
+      })
+      throw error
+    }
+  }, { onEnd: emitSpan })
+}
+// CIL[END chunk_id="agent-runner_runagent_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_resolveagentconfig_1784488696" type="function" identity="resolveAgentConfig" parent="none"]
+// CIL[DOC-LEARNING topic="runtime-type:thread/default_agent" content="agent-runner resolves thread.data.agent_id first, then falls back to thread.type.design_schema.default_agent_id; this lets a thread type define its default AI agent without storing it on every thread."]
+// CIL[DOC-NOTE type="design_schema_caveat" content="If neither thread.data.agent_id nor the thread type's design_schema.default_agent_id is set, the runner logs an error and returns null."]
+// CIL[DOC-MACRO purpose="Resolve agent, prompt config, and thread type from a thread ID"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load thread with type, resolve agent_id and prompt_config_id, then fetch agent and prompt config records"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/migrations/001_schema.sql,.framework/functions/system.ts,.framework/functions/_shared/db.ts,custom/apps/cortex/pages/community/CommunityPage.tsx,.framework/functions/auth.ts,.framework/functions/_shared/resolve-ids.ts,.framework/docs/runtime-types.md"]
+// CIL[DOC-CONTRACT inputs="threadId: string\nctx: CoreContext" outputs="AgentConfig or null" errors="logs and returns null when thread, agent, or prompt config missing" side_effects="DB reads threads, ai_agents, prompt_configs, types; may mutate promptConfig.metadata and agent.model_config.tools with thread.data.cil_config"]
+// CIL[DOC-MICRO logic_summary="Fetches thread with type, chooses thread.data.agent_id or design_schema.default_agent_id, loads active agent, resolves prompt config, merges thread.data.cil_config into promptConfig.metadata.retrieval_policy when enabled, optionally injects CIL tool definitions into agent.model_config.tools and promptConfig.available_tools, and returns config object" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: runAgent. Direct callees: ai_agents(.framework/migrations/001_schema.sql),types(.framework/functions/system.ts),adminDb(.framework/functions/_shared/db.ts),logs(.framework/migrations/001_schema.sql),Thread(custom/apps/cortex/pages/community/CommunityPage.tsx),context(.framework/functions/auth.ts). Related files: .framework/migrations/001_schema.sql,.framework/functions/system.ts,.framework/functions/_shared/db.ts,custom/apps/cortex/pages/community/CommunityPage.tsx,.framework/functions/auth.ts,.framework/functions/_shared/resolve-ids.ts,.framework/docs/runtime-types.md." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: runAgent. Total affected: 1." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [runAgent] and callees [ai_agents(.framework/migrations/001_schema.sql),types(.framework/functions/system.ts),adminDb(.framework/functions/_shared/db.ts),logs(.framework/migrations/001_schema.sql),Thread(custom/apps/cortex/pages/community/CommunityPage.tsx),context(.framework/functions/auth.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+export async function resolveAgentConfig(
+  threadId: string,
+  ctx: CoreContext
+): Promise<AgentConfig | null> {
+  const { data: thread, error: threadError } = await adminDb
+    .from('threads')
+    .select('*, type:types(*)')
+    .eq('id', threadId)
+    .single()
+  if (threadError || !thread) {
+    console.error(`Thread not found: ${threadId}`, threadError)
+    return null
+  }
+  const threadType = thread.type
+  const threadData = thread.data || {}
+  let agentId = threadData.agent_id
+  if (!agentId && threadType?.design_schema?.default_agent_id) {
+    agentId = threadType.design_schema.default_agent_id
+  }
+  if (!agentId) {
+    console.error(`No agent assigned to thread ${threadId}`)
+    return null
+  }
+  const { data: agent, error: agentError } = await adminDb
+    .from('ai_agents')
+    .select('*')
+    .eq('id', agentId)
+    .eq('is_active', true)
+    .single()
+  if (agentError || !agent) {
+    console.error(`Agent not found: ${agentId}`, agentError)
+    return null
+  }
+  const agentMetadata = agent.metadata || {}
+  let promptConfigId = threadData.prompt_config_id
+  if (!promptConfigId && agentMetadata.default_prompt_config_id) {
+    promptConfigId = agentMetadata.default_prompt_config_id
+  }
+  if (!promptConfigId) {
+    console.error(`No prompt config for thread ${threadId}`)
+    return null
+  }
+  const { data: promptConfig, error: configError } = await adminDb
+    .from('prompt_configs')
+    .select('*')
+    .eq('id', promptConfigId)
+    .eq('is_active', true)
+    .single()
+  if (configError || !promptConfig) {
+    console.error(`Prompt config not found: ${promptConfigId}`, configError)
+    return null
+  }
+
+  // Merge optional CIL augmentation config from the thread into the prompt config
+  // retrieval policy. This lets app-level manifest config (e.g. portal) augment
+  // support AI with CIL chunks without changing the ai_agents/prompt_configs rows.
+  if (threadData.cil_config?.enabled) {
+    const existingMetadata = promptConfig.metadata || {}
+    const existingPolicy = existingMetadata.retrieval_policy || {}
+    const existingItemTypes = existingPolicy.item_types
+    // If the prompt config already constrains item_types, add cil_chunk to the
+    // list. If it does not, leave item_types unset so match_embeddings searches
+    // all item types; project_ids will still scope CIL chunks to the configured
+    // projects. This preserves KB/article retrieval and augments with CIL.
+    const newItemTypes = existingItemTypes?.length
+      ? Array.from(new Set([...existingItemTypes, 'cil_chunk']))
+      : undefined
+    promptConfig.metadata = {
+      ...existingMetadata,
+      retrieval_policy: {
+        ...existingPolicy,
+        ...(newItemTypes ? { item_types: newItemTypes } : {}),
+        project_ids: threadData.cil_config.project_ids || [],
+      },
+      cil_config: threadData.cil_config,
+    }
+
+    // When the portal/app config asks for CIL tools, inject them into the agent
+    // and prompt config so the LLM can dispatch CIL lookups during the run.
+    if (threadData.cil_config.use_cil_tools) {
+      agent.model_config = agent.model_config || {}
+      const existingTools = agent.model_config.tools || []
+      const cilToolDefs = CIL_TOOLS.map((t: any) => ({ type: 'function', function: t }))
+      agent.model_config.tools = [...existingTools, ...cilToolDefs]
+      promptConfig.available_tools = [...(promptConfig.available_tools || []), ...CIL_TOOLS.map((t: any) => t.name)]
+    }
+  }
 
-  if (!message?.id) throw new Error('Failed to save message')
-  return message
+  return { agent, promptConfig, thread, threadType }
+}
+// CIL[END chunk_id="agent-runner_resolveagentconfig_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_executeagentinference_1784488696" type="function" identity="executeAgentInference" parent="none"]
+// CIL[DOC-MACRO purpose="Run agent inference with optional tool-calling loop"]
+// CIL[DOC-RESPONSIBILITY responsibility="Build context, call LLM, dispatch tool calls, and compute composite confidence from logprobs and retrieval similarity"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/functions/auth.ts,custom/apps/cortex/functions/custom_kb-chunker-test.ts,custom/apps/portal/hooks/useTickets.ts"]
+// CIL[DOC-CONTRACT inputs="config: AgentConfig\nuserMessage: string\nctx: CoreContext\nmaxToolIterations?: number" outputs="InferenceResult with retrievedSources and retrievalConfidence" errors="throws on max iterations or sub-call failure" side_effects="Calls buildContext, callInference, dispatchTools"]
+// CIL[DOC-MICRO logic_summary="Builds context, loops up to max iterations calling inference and dispatching tools, blends logprob and retrieval similarity for final confidence" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: runAgent. Direct callees: callInference,dispatchTools,buildContext,context(.framework/functions/auth.ts),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts). Related files: .framework/functions/auth.ts,custom/apps/cortex/functions/custom_kb-chunker-test.ts,custom/apps/portal/hooks/useTickets.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: runAgent. Total affected: 1." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [runAgent] and callees [callInference,dispatchTools,buildContext,context(.framework/functions/auth.ts),failed(custom/apps/cortex/functions/custom_kb-chunker-test.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[DOC-NOTE type="tool_loop_limit" content="When the last configured tool iteration still produces tool calls, the runner injects a system note asking the LLM to synthesize a final answer instead of throwing an error. This prevents 'Max tool iterations reached' failures while still capping tool usage via max_tool_iterations."]
+async function executeAgentInference(
+  config: AgentConfig,
+  userMessage: string,
+  ctx: CoreContext,
+  maxToolIterations: number = 5
+): Promise<InferenceResult & { retrievedSources: any[]; retrievalConfidence: number }> {
+  return withSpan(ctx, 'agent.execute_inference', async (ctx) => {
+    const { agent, promptConfig } = config
+    let { context, retrievedSources, meanSimilarity } = await buildContext(config, userMessage, [], ctx)
+    const computeComposite = (llmConf: number): number => {
+      if (meanSimilarity < 0.25 && meanSimilarity > 0) {
+        return Math.min(llmConf * 0.6 + meanSimilarity * 0.4, 0.45)
+      } else if (meanSimilarity < 0.40 && meanSimilarity > 0) {
+        return Math.min(llmConf * 0.6 + meanSimilarity * 0.4, 0.60)
+      }
+      return llmConf * 0.6 + Math.min(meanSimilarity, 1) * 0.4
+    }
+    for (let iteration = 0; iteration < maxToolIterations; iteration++) {
+      const inferenceResult = await callInference(context, agent, promptConfig, ctx)
+      if (!inferenceResult.tool_calls || inferenceResult.tool_calls.length === 0) {
+        const compositeConf = computeComposite(inferenceResult.confidence ?? 0.70)
+        return {
+          ...inferenceResult,
+          confidence: Math.min(Math.max(compositeConf, 0), 1),
+          retrievedSources,
+          retrievalConfidence: meanSimilarity,
+        }
+      }
+      const toolResults = await dispatchTools(inferenceResult.tool_calls, ctx)
+      const rebuilt = await buildContext(config, userMessage, toolResults, ctx)
+      context = rebuilt.context
+      if (rebuilt.retrievedSources.length) {
+        retrievedSources = rebuilt.retrievedSources
+        meanSimilarity = rebuilt.meanSimilarity
+      }
+      if (iteration === maxToolIterations - 1) {
+        const hasErrors = toolResults.some(r => r.error)
+        const note = `\n\n[System note: You have reached the tool limit. Do not call any more tools. Synthesize your final answer based on the information and tool results already provided.${hasErrors ? ' Some tools failed.' : ''}]`
+        const finalResult = await callInference(context + note, agent, promptConfig, ctx)
+        if (finalResult.tool_calls?.length) {
+          finalResult.content = (finalResult.content || '') + '\n\n[Note: I reached the tool limit and still attempted to call tools. The response may be incomplete.]'
+        }
+        const compositeConf = computeComposite(finalResult.confidence ?? 0.70)
+        return {
+          ...finalResult,
+          confidence: Math.min(Math.max(compositeConf, 0), 1),
+          retrievedSources,
+          retrievalConfidence: meanSimilarity,
+        }
+      }
+    }
+    throw new Error('Max tool iterations reached')
+  }, { onEnd: emitSpan })
+}
+// CIL[END chunk_id="agent-runner_executeagentinference_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_executecilchunklookup_1784488696" type="function" identity="executeCilChunkLookup" parent="agent-runner_ciltools_1784488696"]
+// CIL[DOC-MACRO purpose="Tool handler: cil_chunk_lookup"]
+// CIL[DOC-RESPONSIBILITY responsibility="Search CIL chunks by name, file path, or purpose"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files="custom/apps/cortex/functions/custom_cil-agent.ts"]
+// CIL[DOC-CONTRACT inputs="params: { q, project_id?, limit? }\nctx: CoreContext" outputs="{ results, count }" errors="throws on DB failure" side_effects="DB read on items table"]
+// CIL[DOC-MICRO logic_summary="Queries active cil_chunk items for the account, filters by project_id and search term, and returns a trimmed result list" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: executeToolAction. Direct callees: adminDb(.framework/functions/_shared/db.ts). Related files: custom/apps/cortex/functions/custom_cil-agent.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: executeToolAction. Total affected: 1." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [executeToolAction] and callees [adminDb(.framework/functions/_shared/db.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+async function executeCilChunkLookup(params: any, ctx: CoreContext): Promise<any> {
+  const { q, project_id, limit = 5 } = params
+  if (!q) throw new Error('q is required')
+
+  let query = adminDb
+    .from('items')
+    .select('id, title, data')
+    .filter('data->>kb_type', 'eq', 'cil_chunk')
+    .eq('account_id', ctx.accountId)
+    .eq('is_active', true)
+    .limit(50)
+
+  if (project_id) {
+    query = query.filter('data->>project_id', 'eq', project_id)
+  }
+
+  const { data, error } = await query
+  if (error) throw error
+
+  const term = String(q).toLowerCase()
+  const matches = (data || [])
+    .filter((item: any) => {
+      const d = item.data || {}
+      const haystack = [
+        item.title || '',
+        d.chunk_name || '',
+        d.file_path || '',
+        d.macro || '',
+        d.micro || '',
+      ].join(' ').toLowerCase()
+      return haystack.includes(term)
+    })
+    .slice(0, limit)
+    .map((item: any) => {
+      const d = item.data || {}
+      return {
+        chunk_id: item.id,
+        chunk_name: d.chunk_name,
+        file_path: d.file_path,
+        chunk_type: d.chunk_type,
+        macro: d.macro,
+        stability: d.stability,
+      }
+    })
+
+  return { results: matches, count: matches.length }
+}
+// CIL[END chunk_id="agent-runner_executecilchunklookup_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_executecilgetcontract_1784488696" type="function" identity="executeCilGetContract" parent="agent-runner_ciltools_1784488696"]
+// CIL[DOC-MACRO purpose="Tool handler: cil_get_contract"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return the full contract and metadata for a CIL chunk"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files="custom/apps/cortex/functions/custom_cil-agent.ts"]
+// CIL[DOC-CONTRACT inputs="params: { chunk_id }\nctx: CoreContext" outputs="chunk contract object" errors="throws if chunk not found" side_effects="DB read on items table"]
+// CIL[DOC-MICRO logic_summary="Fetches a cil_chunk item by UUID and returns its contract fields" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: executeToolAction. Direct callees: adminDb(.framework/functions/_shared/db.ts). Related files: custom/apps/cortex/functions/custom_cil-agent.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: executeToolAction. Total affected: 1." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [executeToolAction] and callees [adminDb(.framework/functions/_shared/db.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+async function executeCilGetContract(params: any, ctx: CoreContext): Promise<any> {
+  const { chunk_id } = params
+  if (!chunk_id) throw new Error('chunk_id is required')
+
+  const { data, error } = await adminDb
+    .from('items')
+    .select('id, title, data')
+    .eq('id', chunk_id)
+    .filter('data->>kb_type', 'eq', 'cil_chunk')
+    .eq('account_id', ctx.accountId)
+    .single()
+
+  if (error || !data) throw new Error(`CIL chunk not found: ${chunk_id}`)
+
+  const d = data.data || {}
+  return {
+    chunk_id: data.id,
+    chunk_name: d.chunk_name,
+    chunk_type: d.chunk_type,
+    file_path: d.file_path,
+    macro: d.macro,
+    responsibility: d.responsibility,
+    contract: {
+      inputs: d.input_spec,
+      outputs: d.output_spec,
+      errors: d.error_spec,
+      side_effects: d.side_effects,
+    },
+    micro: d.micro,
+    stability: d.stability,
+    confidence: d.confidence,
+    audience: d.audience,
+  }
+}
+// CIL[END chunk_id="agent-runner_executecilgetcontract_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_executecilblastradius_1784488696" type="function" identity="executeCilBlastRadius" parent="agent-runner_ciltools_1784488696"]
+// CIL[DOC-MACRO purpose="Tool handler: cil_blast_radius"]
+// CIL[DOC-RESPONSIBILITY responsibility="Find chunks transitively linked to a given chunk"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files="custom/apps/cortex/functions/custom_cil-callmap.ts"]
+// CIL[DOC-CONTRACT inputs="params: { chunk_id, max_depth? }\nctx: CoreContext" outputs="{ chunk_id, max_depth, affected }" errors="throws on DB failure" side_effects="DB reads on link_types and links tables"]
+// CIL[DOC-MICRO logic_summary="Resolves CIL link type IDs, performs BFS over links, and joins chunk metadata" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: executeToolAction. Direct callees: adminDb(.framework/functions/_shared/db.ts). Related files: custom/apps/cortex/functions/custom_cil-callmap.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: executeToolAction. Total affected: 1." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [executeToolAction] and callees [adminDb(.framework/functions/_shared/db.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+async function executeCilBlastRadius(params: any, ctx: CoreContext): Promise<any> {
+  const { chunk_id, max_depth = 3 } = params
+  if (!chunk_id) throw new Error('chunk_id is required')
+
+  const maxDepth = Math.min(parseInt(max_depth, 10) || 3, 6)
+
+  const { data: linkTypes, error: ltError } = await adminDb
+    .from('link_types')
+    .select('id, slug')
+    .eq('account_id', ctx.accountId)
+    .in('slug', ['cil_imports', 'cil_calls', 'cil_exports', 'cil_tested_by'])
+
+  if (ltError) throw ltError
+  const linkTypeIds = (linkTypes || []).map((lt: any) => lt.id)
+  if (linkTypeIds.length === 0) return { chunk_id, max_depth: maxDepth, affected: [] }
+
+  const visited = new Set<string>()
+  const affected: any[] = []
+  const frontier: { id: string; depth: number }[] = [{ id: chunk_id, depth: 0 }]
+
+  while (frontier.length > 0) {
+    const current = frontier.shift()!
+    if (visited.has(current.id)) continue
+    visited.add(current.id)
+
+    const [sourceLinks, targetLinks] = await Promise.all([
+      adminDb
+        .from('links')
+        .select('id, source_id, target_id, link_type_id, data')
+        .eq('source_id', current.id)
+        .in('link_type_id', linkTypeIds),
+      adminDb
+        .from('links')
+        .select('id, source_id, target_id, link_type_id, data')
+        .eq('target_id', current.id)
+        .in('link_type_id', linkTypeIds),
+    ])
+
+    const allLinks = [...(sourceLinks.data || []), ...(targetLinks.data || [])]
+    for (const link of allLinks) {
+      const neighborId = link.source_id === current.id ? link.target_id : link.source_id
+      if (visited.has(neighborId)) continue
+      affected.push({
+        chunk_id: neighborId,
+        link_type_id: link.link_type_id,
+        depth: current.depth + 1,
+      })
+      if (current.depth + 1 < maxDepth) {
+        frontier.push({ id: neighborId, depth: current.depth + 1 })
+      }
+    }
+  }
+
+  const chunkIds = affected.map(a => a.chunk_id)
+  const { data: items } = await adminDb
+    .from('items')
+    .select('id, title, data')
+    .in('id', chunkIds)
+    .filter('data->>kb_type', 'eq', 'cil_chunk')
+    .eq('account_id', ctx.accountId)
+
+  const itemMap = new Map((items || []).map((i: any) => [i.id, i]))
+
+  return {
+    chunk_id,
+    max_depth: maxDepth,
+    affected: affected.map((a: any) => {
+      const item = itemMap.get(a.chunk_id)
+      const d = item?.data || {}
+      return {
+        ...a,
+        chunk_name: d.chunk_name,
+        file_path: d.file_path,
+        link_slug: linkTypes?.find((lt: any) => lt.id === a.link_type_id)?.slug,
+      }
+    }),
+  }
+}
+// CIL[END chunk_id="agent-runner_executecilblastradius_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_executecilhashvalidate_1784488696" type="function" identity="executeCilHashValidate" parent="agent-runner_ciltools_1784488696"]
+// CIL[DOC-MACRO purpose="Tool handler: cil_hash_validate"]
+// CIL[DOC-RESPONSIBILITY responsibility="Compare a CIL chunk's stored hash to its stored code_content"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/mcp/tools/cil/validate.ts"]
+// CIL[DOC-CONTRACT inputs="params: { chunk_id }\nctx: CoreContext" outputs="{ chunk_id, stored_hash, computed_hash, is_current, hash_updated_at }" errors="throws if chunk not found" side_effects="DB read on items table"]
+// CIL[DOC-MICRO logic_summary="Fetches cil_chunk by UUID, normalises its code_content, computes hash, and compares to stored_hash" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: executeToolAction. Direct callees: adminDb(.framework/functions/_shared/db.ts). Related files: .framework/mcp/tools/cil/validate.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: executeToolAction. Total affected: 1." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [executeToolAction] and callees [adminDb(.framework/functions/_shared/db.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+async function executeCilHashValidate(params: any, ctx: CoreContext): Promise<any> {
+  const { chunk_id } = params
+  if (!chunk_id) throw new Error('chunk_id is required')
+
+  const { data, error } = await adminDb
+    .from('items')
+    .select('id, title, data')
+    .eq('id', chunk_id)
+    .filter('data->>kb_type', 'eq', 'cil_chunk')
+    .eq('account_id', ctx.accountId)
+    .single()
+
+  if (error || !data) throw new Error(`CIL chunk not found: ${chunk_id}`)
+
+  const d = data.data || {}
+  const codeContent = d.code_content || ''
+  const storedHash = d.stored_hash
+  const computedHash = computeCilChunkHash(codeContent)
+
+  return {
+    chunk_id,
+    stored_hash: storedHash,
+    computed_hash: computedHash,
+    is_current: storedHash === computedHash,
+    hash_updated_at: d.hash_updated_at,
+  }
+}
+// CIL[END chunk_id="agent-runner_executecilhashvalidate_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_executecilprojectstatus_1784488696" type="function" identity="executeCilProjectStatus" parent="agent-runner_ciltools_1784488696"]
+// CIL[DOC-MACRO purpose="Tool handler: cil_project_status"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return CIL pipeline status for a project"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files="custom/apps/cortex/functions/custom_cil-project.ts"]
+// CIL[DOC-CONTRACT inputs="params: { project_id }\nctx: CoreContext" outputs="{ project_id, title, file_count, chunk_count, embedding_coverage_pct, doc_coverage_pct, last_ingested_at }" errors="throws if project not found" side_effects="DB reads on items table"]
+// CIL[DOC-MICRO logic_summary="Fetches the cil_project item; if summary fields are missing it computes live counts from related cil_file and cil_chunk items" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: executeToolAction. Direct callees: adminDb(.framework/functions/_shared/db.ts). Related files: custom/apps/cortex/functions/custom_cil-project.ts." status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: executeToolAction. Total affected: 1." status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="Config dependencies: none. Test paths: none." status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="Driven by chunk inputs; callers [executeToolAction] and callees [adminDb(.framework/functions/_shared/db.ts)] shape downstream behavior." status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+async function executeCilProjectStatus(params: any, ctx: CoreContext): Promise<any> {
+  const { project_id } = params
+  if (!project_id) throw new Error('project_id is required')
+
+  const { data: project, error: projectError } = await adminDb
+    .from('items')
+    .select('id, title, data')
+    .eq('id', project_id)
+    .filter('data->>kb_type', 'eq', 'cil_project')
+    .eq('account_id', ctx.accountId)
+    .single()
+
+  if (projectError || !project) throw new Error(`CIL project not found: ${project_id}`)
+
+  const d = project.data || {}
+
+  if (d.file_count !== undefined && d.chunk_count !== undefined) {
+    return {
+      project_id,
+      title: project.title,
+      file_count: d.file_count,
+      chunk_count: d.chunk_count,
+      embedding_coverage_pct: d.embedding_coverage_pct ?? 0,
+      doc_coverage_pct: d.doc_coverage_pct ?? 0,
+      last_ingested_at: d.last_ingested_at,
+    }
+  }
+
+  const [fileRes, chunkRes] = await Promise.all([
+    adminDb
+      .from('items')
+      .select('*', { count: 'exact' })
+      .filter('data->>project_id', 'eq', project_id)
+      .filter('data->>kb_type', 'eq', 'cil_file')
+      .eq('is_active', true),
+    adminDb
+      .from('items')
+      .select('*', { count: 'exact' })
+      .filter('data->>project_id', 'eq', project_id)
+      .filter('data->>kb_type', 'eq', 'cil_chunk')
+      .eq('is_active', true),
+  ])
+
+  return {
+    project_id,
+    title: project.title,
+    file_count: fileRes.count || 0,
+    chunk_count: chunkRes.count || 0,
+    embedding_coverage_pct: d.embedding_coverage_pct ?? 0,
+    doc_coverage_pct: d.doc_coverage_pct ?? 0,
+    last_ingested_at: d.last_ingested_at,
+  }
+}
+// CIL[END chunk_id="agent-runner_executecilprojectstatus_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_executesearchlogs_1784488696" type="function" identity="executeSearchLogs" parent="none"]
+// CIL[DOC-MACRO purpose="Tool handler: search_logs for runtime and trace logs"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query public.logs for the current account, optionally filtered by level and message substring"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/migrations/005_core_observability.sql"]
+// CIL[DOC-CONTRACT inputs="params: { q, level, limit? }\nctx: CoreContext" outputs="{ results }" errors="throws on DB failure" side_effects="DB read on logs table"]
+// CIL[DOC-MICRO logic_summary="Text-search recent logs scoped to account, ordered by created_at desc" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="developer"]
+async function executeSearchLogs(params: any, ctx: CoreContext): Promise<any> {
+  const { q, level, limit = 20 } = params
+  let query = adminDb
+    .from('logs')
+    .select('id, app_id, type_id, level, message, context, metadata, created_at')
+    .eq('account_id', ctx.accountId)
+    .order('created_at', { ascending: false })
+    .limit(limit)
+  if (level) query = query.eq('level', level)
+  if (q) query = query.or(`message.ilike.%${q}%,context->>trace.ilike.%${q}%`)
+  const { data, error } = await query
+  if (error) throw error
+  return { results: data || [], count: (data || []).length }
+}
+// CIL[END chunk_id="agent-runner_executesearchlogs_1784488696"]
+// CIL[BEGIN chunk_id="agent-runner_executesearchobservability_1784488696" type="function" identity="executeSearchObservability" parent="none"]
+// CIL[DOC-MACRO purpose="Tool handler: search_observability for metrics and traces"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query public.observability for the current account, optionally filtered by metric name"]
+// CIL[DOC-CONTEXT module="_shared/agent-runner" layer="infrastructure" related_files=".framework/migrations/005_core_observability.sql"]
+// CIL[DOC-CONTRACT inputs="params: { metric_name, limit? }\nctx: CoreContext" outputs="{ results }" errors="throws on DB failure" side_effects="DB read on observability table"]
+// CIL[DOC-MICRO logic_summary="Fetch recent observability metrics scoped to account, ordered by created_at desc" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="developer"]
+async function executeSearchObservability(params: any, ctx: CoreContext): Promise<any> {
+  const { metric_name, limit = 20 } = params
+  let query = adminDb
+    .from('observability')
+    .select('id, app_id, type_id, metric_name, metric_value, metric_unit, context, metadata, created_at')
+    .eq('account_id', ctx.accountId)
+    .order('created_at', { ascending: false })
+    .limit(limit)
+  if (metric_name) query = query.eq('metric_name', metric_name)
+  const { data, error } = await query
+  if (error) throw error
+  return { results: data || [], count: (data || []).length }
 }
+// CIL[END chunk_id="agent-runner_executesearchobservability_1784488696"]