spine-framework 0.3.145 → 0.4.1

package/.framework/functions/ai-agents.ts

@@ -1,46 +1,114 @@
+// CIL[BEGIN stable_id="~/.framework/functions/ai-agents.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/ai-agents.ts"]
+/**
+ * @module   functions/ai-agents
+ * @audience internal
+ * @layer    app-specific
+ * @stability stable
+ *
+ * This module provides functionality for AI agents within the application, facilitating their execution and management. It integrates middleware for handling requests, checks permissions, and manages rate limits to ensure system integrity. INVARIANT: Only system administrators can execute certain actions related to agents.
+ *
+ * @seeAlso functions/_shared/middleware (provides request handling)
+ * @seeAlso functions/_shared/permissions (manages access control)
+ * @seeAlso functions/_shared/rate-limit (ensures system stability)
+ * @seeAlso functions/_shared/agent-runner (executes agent logic)
+ *
+ * @cil-generated
+ */
+
+
+
+
+
 
 
 
 
 
 
-// CIL[BEGIN chunk_id="ai-agents_module_header_1784019432" type="module_header" identity="imports" parent="none"]
-// CIL[DOC-MACRO purpose="Import dependencies for AI agents CRUD operations"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide core middleware, database joins, audit logging, and permissions"]
-// CIL[DOC-CONTEXT module="ai-agents" layer="api-handler" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="imported_modules" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports required modules and configures permissions engine" 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: api-handler. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/principal.ts, custom/apps/portal/pages/ContentPage.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { createHandler } from './_shared/middleware'
 import { adminDb } from './_shared/db'
 import { emitLog } from './_shared/audit'
 import { isSystemAdmin } from './_shared/principal'
 import { PermissionEngine, sanitizeRecordData } from './_shared/permissions'
+import { runAgent, kickAgentEpisode } from './_shared/agent-runner'
+import { checkRateLimit } from './_shared/rate-limit'
+import { detectInjection, emitSecurityEvent, getAppSecurityConfig } from './_shared/security'
+// CIL[END stable_id="~/.framework/functions/ai-agents.ts:module_header:module_header"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/ai-agents.ts:permissions:constant" type="constant" identity="permissions" parent="~/.framework/functions/ai-agents.ts"]
+/**
+ * The 'permissions' constant provides access to the PermissionEngine, allowing for permission management within the module. It exists to facilitate the handling of user permissions in AI agent functionalities.
+ *
+ * @sideEffects none
+ * @stability   stable
+ * @cil-generated
+ */
+
+
+
+
+
+
+
 
 const permissions = PermissionEngine as any
-// CIL[END chunk_id="ai-agents_module_header_1784019432"]
-// CIL[BEGIN chunk_id="ai-agents_list_1784019432" type="function" identity="list" parent="none"]
-// CIL[DOC-MACRO purpose="List AI agents with filtering and pagination"]
-// CIL[DOC-RESPONSIBILITY responsibility="Query and sanitize AI agent records"]
-// CIL[DOC-CONTEXT module="ai-agents" layer="api-handler" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="sanitized_agent_records[]" errors="account_required,database_error" side_effects="database_queries,permission_filtering"]
-// CIL[DOC-MICRO logic_summary="Builds query with filters, applies pagination, sanitizes 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: api-handler. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/schema-utils.ts, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/ai-agents.ts:permissions:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/ai-agents.ts:list:constant" type="constant" identity="list" parent="~/.framework/functions/ai-agents.ts"]
+/**
+ * Fetches a list of AI agents based on query parameters such as agent type and active status. This function is designed to provide a sanitized view of AI agents for the requesting account.
+ *
+ * @throws      Error — Account context required.
+ * @sideEffects none
+ * @stability   stable
+ * @calls       isSystemAdmin, adminDb.from, ctx.db.from, sanitizeRecordData
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
 export const list = createHandler(async (ctx, _body) => {
   const { agent_type, is_active, limit = 100, offset = 0 } = ctx.query || {}
 
@@ -76,21 +144,41 @@ export const list = createHandler(async (ctx, _body) => {
 
   return sanitized
 })
-// CIL[END chunk_id="ai-agents_list_1784019432"]
-// CIL[BEGIN chunk_id="ai-agents_get_1784019432" type="function" identity="get" parent="none"]
-// CIL[DOC-MACRO purpose="Get single AI agent by ID with joins"]
-// CIL[DOC-RESPONSIBILITY responsibility="Retrieve and sanitize individual agent record"]
-// CIL[DOC-CONTEXT module="ai-agents" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="sanitized_agent_record" errors="id_required,record_not_found,database_error" side_effects="database_query,permission_filtering"]
-// CIL[DOC-MICRO logic_summary="Queries single agent by ID, applies permission sanitization" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/RolesPage.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/ai-agents.ts:list:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/ai-agents.ts:get:constant" type="constant" identity="get" parent="~/.framework/functions/ai-agents.ts"]
+/**
+ * Fetches an AI agent record by its ID from the database. This function ensures that only authorized users can access the data based on their role.
+ *
+ * @throws      Error — Agent ID is required, Error — database query error
+ * @sideEffects none
+ * @stability   stable
+ * @calls       adminDb.from('ai_agents'), ctx.db.from('ai_agents'), sanitizeRecordData
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
 export const get = createHandler(async (ctx, _body) => {
   const { id } = ctx.query || {}
 
@@ -110,21 +198,41 @@ export const get = createHandler(async (ctx, _body) => {
 
   return await sanitizeRecordData(ctx, data, 'ai_agent')
 })
-// CIL[END chunk_id="ai-agents_get_1784019432"]
-// CIL[BEGIN chunk_id="ai-agents_create_1784019432" type="function" identity="create" parent="none"]
-// CIL[DOC-MACRO purpose="Create new AI agent configuration"]
-// CIL[DOC-RESPONSIBILITY responsibility="Validate and insert new agent record with audit logging"]
-// CIL[DOC-CONTEXT module="ai-agents" layer="api-handler" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="created_agent_record" errors="name_required,user_context_required,database_error" side_effects="database_insert,audit_logging"]
-// CIL[DOC-MICRO logic_summary="Validates required fields, inserts with defaults, logs creation" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/components/ui/dialog.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/ai-agents.ts:get:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/ai-agents.ts:create:constant" type="constant" identity="create" parent="~/.framework/functions/ai-agents.ts"]
+/**
+ * Creates a new AI agent in the database based on the provided parameters. It ensures that required fields are present and that the user context is valid before performing the insertion.
+ *
+ * @throws      Error — name and agent_type are required; Error — User context (person and account) required; Error — database insertion error.
+ * @sideEffects Inserts a new record into the 'ai_agents' table; emits a log event for the creation of the AI agent.
+ * @stability   stable
+ * @calls       ctx.db.from('ai_agents'), emitLog
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
 export const create = createHandler(async (ctx, body) => {
   const { app_id, name, description, agent_type, model_config, system_prompt, tools, capabilities, constraints, metadata } = body
 
@@ -164,21 +272,41 @@ export const create = createHandler(async (ctx, body) => {
 
   return data
 })
-// CIL[END chunk_id="ai-agents_create_1784019432"]
-// CIL[BEGIN chunk_id="ai-agents_update_1784019432" type="function" identity="update" parent="none"]
-// CIL[DOC-MACRO purpose="Update existing AI agent configuration"]
-// CIL[DOC-RESPONSIBILITY responsibility="Patch allowed fields on agent record with audit logging"]
-// CIL[DOC-CONTEXT module="ai-agents" layer="api-handler" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="updated_agent_record" errors="id_required,user_context_required,database_error" side_effects="database_update,audit_logging"]
-// CIL[DOC-MICRO logic_summary="Filters allowed fields, adds timestamp, updates with validation" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/ai-agents.ts:create:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/ai-agents.ts:update:constant" type="constant" identity="update" parent="~/.framework/functions/ai-agents.ts"]
+/**
+ * Updates an AI agent's properties in the database based on the provided ID and update data. It ensures that the user context is valid and that the ID is provided before performing the update.
+ *
+ * @throws      Error — Agent ID is required, Error — User context (person and account) required
+ * @sideEffects Database update on 'ai_agents' table, logging of the update event.
+ * @stability   stable
+ * @calls       ctx.db.from('ai_agents'), emitLog
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
 export const update = createHandler(async (ctx, body) => {
   const id = body?.id || ctx.query?.id
   const { id: _bodyId, ...updates } = body || {}
@@ -213,21 +341,41 @@ export const update = createHandler(async (ctx, body) => {
 
   return data
 })
-// CIL[END chunk_id="ai-agents_update_1784019432"]
-// CIL[BEGIN chunk_id="ai-agents_remove_1784019432" type="function" identity="remove" parent="none"]
-// CIL[DOC-MACRO purpose="Delete AI agent configuration"]
-// CIL[DOC-RESPONSIBILITY responsibility="Hard delete agent record with audit logging"]
-// CIL[DOC-CONTEXT module="ai-agents" layer="api-handler" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="success_confirmation" errors="id_required,agent_not_found,database_error" side_effects="database_delete,audit_logging"]
-// CIL[DOC-MICRO logic_summary="Validates existence, performs hard delete, logs deletion" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/ai-agents.ts:update:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/ai-agents.ts:remove:constant" type="constant" identity="remove" parent="~/.framework/functions/ai-agents.ts"]
+/**
+ * The 'remove' constant defines a handler for deleting an AI agent from the database based on its ID. It ensures that the ID is provided and logs the deletion event.
+ *
+ * @throws      Error — Agent ID is required, Error — Agent not found, Error — database error during deletion
+ * @sideEffects Deletes an entry from the 'ai_agents' table, emits a log event.
+ * @stability   stable
+ * @calls       ctx.db.from('ai_agents'), ctx.db.select, ctx.db.eq, ctx.db.single, ctx.db.delete, emitLog
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
 export const remove = createHandler(async (ctx, _body) => {
   const id = ctx.query?.id
 
@@ -257,26 +405,196 @@ export const remove = createHandler(async (ctx, _body) => {
 
   return { success: true }
 })
-// CIL[END chunk_id="ai-agents_remove_1784019432"]
-// CIL[BEGIN chunk_id="ai-agents_handler_1784019432" type="function" identity="handler" parent="none"]
-// CIL[DOC-MACRO purpose="Route HTTP methods to appropriate CRUD handlers"]
-// CIL[DOC-RESPONSIBILITY responsibility="Dispatch requests based on method and query parameters"]
-// CIL[DOC-CONTEXT module="ai-agents" layer="api-handler" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="handler_response" errors="invalid_action_or_method" side_effects="delegates_to_crud_handlers"]
-// CIL[DOC-MICRO logic_summary="Routes GET/POST/PATCH/DELETE to list/get/create/update/remove" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/ai-agents.ts:remove:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/ai-agents.ts:run:constant" type="constant" identity="run" parent="~/.framework/functions/ai-agents.ts"]
+/**
+ * The 'run' constant defines an asynchronous handler that processes user messages within a specified thread context. It ensures that necessary parameters are provided and manages the execution of an agent based on the provided mode.
+ *
+ * @throws      Error — thread_id is required, Error — User context (person and account) required, Error — Thread not found
+ * @sideEffects Database reads from 'threads' and updates to 'threads' based on agent execution.
+ * @stability   stable
+ * @calls       checkRateLimit, runAgent, adminDb.from('threads'), adminDb.select, adminDb.eq, adminDb.single
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
+export const run = createHandler(async (ctx, body) => {
+  const { thread_id, user_message, mode } = body || {}
+  if (!thread_id) {
+    throw new Error('thread_id is required')
+  }
+  if (!ctx.principal || ctx.principal.id === 'anonymous' || !ctx.accountId) {
+    throw new Error('User context (person and account) required')
+  }
+
+  const { data, error: err } = await ctx.db
+    .from('threads')
+    .select('*, type:types(*)')
+    .eq('id', thread_id)
+    .single()
+  if (err || !data) throw new Error(err?.message || 'Thread not found')
+
+  // Prompt-injection pre-flight. Mode comes from the calling app's
+  // config.security.prompt_injection: 'off' | 'flag' (default) | 'block'.
+  // 'block' refuses before any tokens are spent — callers translate the
+  // error into human-routing; 'flag' audits the hit so the security
+  // report can aggregate repeat offenders.
+  const injectionHit = detectInjection(user_message)
+  if (injectionHit) {
+    const secCfg = await getAppSecurityConfig(ctx.appId)
+    const injectionMode = secCfg?.prompt_injection ?? 'flag'
+    void emitSecurityEvent(ctx, 'security.injection_detected', {
+      type: 'thread', id: thread_id, account_id: ctx.accountId
+    }, {
+      result: injectionMode === 'block' ? 'denied' : 'flagged',
+      pattern: injectionHit,
+      injection_mode: injectionMode,
+    })
+    if (injectionMode === 'block') {
+      const e: any = new Error('Your message could not be processed automatically. A support specialist will review it.')
+      e.statusCode = 400
+      throw e
+    }
+  }
+
+  const runMode = (mode as 'step' | 'complete' | 'episode') || 'complete'
+
+  // Episode single-flight: the in-flight driver stamps driver_id +
+  // driver_heartbeat_at into research_state. A different driver asking to
+  // step/kick while the lease is fresh gets 'running' instead of a second
+  // interleaved write pass. The owner itself is never refused (its own
+  // staleness check is finer-grained), and a lease expires after
+  // DRIVER_LEASE_MS so a crashed driver can't wedge the thread.
+  const DRIVER_LEASE_MS = 60000
+  const existingState = (data as any)?.data?.research_state
+  const heartbeatAt = Date.parse(existingState?.driver_heartbeat_at || '')
+  const leaseHolder = existingState?.driver_id
+  const callerToken = (body?.driver_token as string) || null
+  const callerId = callerToken || ctx.requestId
+  const leaseLive =
+    !!leaseHolder &&
+    leaseHolder !== callerId &&
+    !!existingState?.status &&
+    !['complete', 'awaiting_input', 'failed'].includes(existingState.status) &&
+    Number.isFinite(heartbeatAt) &&
+    Date.now() - heartbeatAt < DRIVER_LEASE_MS
+
+  if ((runMode === 'step' || runMode === 'complete') && leaseLive) {
+    return { ok: true, thread_id, status: 'running', driver_id: leaseHolder }
+  }
+
+  if (runMode === 'episode') {
+    if (leaseLive) {
+      return { ok: true, thread_id, status: 'running', detached: true, already_running: true }
+    }
+    // Debit agent_step only when a new driver will actually start work —
+    // lease-refused requests and ticket-creation kicks already debited or
+    // started nothing, and counting them would double-charge each episode.
+    await checkRateLimit(ctx, 'agent_step')
+    // Claim the lease before detaching so a step request landing during
+    // resolveAgentConfig still sees a live driver. Shared implementation lives
+    // in kickAgentEpisode (also used by ticket-creation handlers).
+    const leaseId = callerToken || ctx.requestId
+    const kick = await kickAgentEpisode(thread_id, user_message || '', ctx, leaseId, (data as any)?.data)
+    if (!kick.claimed) {
+      return { ok: true, thread_id, status: 'running', detached: true, already_running: true }
+    }
+    return { ok: true, thread_id, status: 'running', detached: true }
+  }
+
+  // step/complete modes debit here — same rule: only when work will start.
+  await checkRateLimit(ctx, 'agent_step')
+  const message = await runAgent(thread_id, user_message || '', ctx, runMode, callerToken || undefined)
+
+  const { data: updatedThread } = await adminDb
+    .from('threads')
+    .select('data')
+    .eq('id', thread_id)
+    .single()
+
+  const state = updatedThread?.data?.research_state || {}
+  const messageType = message?.data?.message_type ||
+    (state.status === 'awaiting_input' ? 'awaiting_input' : 'final')
+
+  return {
+    ok: true,
+    thread_id,
+    message_id: message?.id || null,
+    status: state.status || (message ? 'complete' : 'failed'),
+    turn_count: state.turn_count ?? 0,
+    content: message?.content || '',
+    message_type: messageType,
+    data: message?.data || null,
+    // Intermediate research messages (tool_call/tool_result/plan) don't carry
+    // agent/prompt ids — fall back to the thread's resolved config.
+    agent_id: message?.data?.agent_id || updatedThread?.data?.agent_id || null,
+    prompt_config_id: message?.data?.prompt_config_id || updatedThread?.data?.prompt_config_id || null,
+  }
+})
+// CIL[END stable_id="~/.framework/functions/ai-agents.ts:run:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/ai-agents.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/ai-agents.ts"]
+/**
+ * The handler processes incoming requests based on the specified action and HTTP method, routing them to the appropriate function. It exists to manage different operations like retrieving, creating, or deleting resources in a structured manner.
+ *
+ * @throws      Error — Invalid action or method
+ * @sideEffects none
+ * @stability   stable
+ * @calls       run, get, list, create, remove
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
 export const handler = createHandler(async (ctx, body) => {
   const { action } = ctx.query || {}
   const method = ctx.query?.method || 'GET'
 
   switch (action) {
+    case 'run':
+      return await run(ctx, body)
     default:
       if (method === 'GET') {
         if (ctx.query?.id) {
@@ -295,4 +613,11 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error('Invalid action or method')
 })
-// CIL[END chunk_id="ai-agents_handler_1784019432"]
+// CIL[END stable_id="~/.framework/functions/ai-agents.ts:handler:constant"]
+
+
+
+
+
+
+