spine-framework 0.3.124 → 0.3.126

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

@@ -1,62 +1,46 @@
-/**
- * @module ai-agents
- * @audience core-contributor
- * @layer api-handler
- * @stability stable
- *
- * CRUD API for the `ai_agents` table. AI agent records define the configuration
- * for agentic inference workloads: model settings, system prompts, available
- * tools, capabilities, and constraints. The runtime execution is handled by
- * `_shared/agent-runner.ts`.
- *
- * **Routed by:** `GET/POST/PATCH/DELETE /.netlify/functions/ai-agents`
- *
- * **Actions (standard CRUD only):**
- * | method | condition | handler |
- * |--------|-----------|---------|
- * | GET    | ?id       | get     |
- * | GET    | (default) | list    |
- * | POST   | —         | create  |
- * | PATCH  | —         | update  |
- * | DELETE | —         | remove  |
- *
- * **Authorization:** All operations use `ctx.db` (RLS-scoped). Authenticated
- * principal required for writes.
- *
- * INVARIANT: `remove` is a hard delete.
- * INVARIANT: `update` only patches allowed fields: name, description,
- *   model_config, system_prompt, tools, capabilities, constraints, metadata,
- *   is_active.
- *
- * @seeAlso agent-runner.ts (runAgent — runtime execution using these configs)
- * @seeAlso prompt-configs.ts (prompt_configs referenced by agent configs)
- * @seeAlso audit.ts (emitLog for ai_agent.* events)
- */
 
+
+
+
+
+
+// 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 { joins } from './_shared/db'
+import { adminDb } from './_shared/db'
 import { emitLog } from './_shared/audit'
+import { isSystemAdmin } from './_shared/principal'
 import { PermissionEngine, sanitizeRecordData } from './_shared/permissions'
 
 const permissions = PermissionEngine as any
-
-// ─── HANDLERS ─────────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: AI_AGENTS_LIST ──────────────────────────────────────────────
-/**
- * @chunk-id    AI_AGENTS_LIST_1_0_0
- * @version     1.0.0
- * @hash        237972d65e86f5d432f55b602ac5e6f2dcfaefa83c662c10b7d3437ac906ff0d
- * @macro       AI Agents List Handler
- * @micro       Lists AI agents with filtering and pagination
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     Array of sanitized AI agent records
- * @depends-on  [createHandler, joins, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB queries, permission sanitization]
- * @tags        ai-agents, list, crud, pagination
- */
+// 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"]
 export const list = createHandler(async (ctx, _body) => {
   const { agent_type, is_active, limit = 100, offset = 0 } = ctx.query || {}
 
@@ -64,10 +48,11 @@ export const list = createHandler(async (ctx, _body) => {
     throw new Error('Account context required')
   }
 
-  // RLS automatically filters to accessible accounts
-  let query = ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+
+  let query = db
     .from('ai_agents')
-    .select(`*, ${joins.app}, ${joins.createdBy}`)
+    .select('*')
     .order('name')
 
   if (agent_type) {
@@ -91,23 +76,21 @@ export const list = createHandler(async (ctx, _body) => {
 
   return sanitized
 })
-// ─── CHUNK_END: AI_AGENTS_LIST ────────────────────────────────────────────────
-
-// ─── CHUNK_START: AI_AGENTS_GET ──────────────────────────────────────────────
-/**
- * @chunk-id    AI_AGENTS_GET_1_0_0
- * @version     1.0.0
- * @hash        62f283668d9a90ff81e2cbf8c437298206b355d2dd96fb559b2848fc4ffbc5cd
- * @macro       AI Agent Get Handler
- * @micro       Returns a single AI agent by UUID with joins
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     Sanitized AI agent record with app and createdBy joins
- * @depends-on  [createHandler, joins, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB single row query, permission sanitization]
- * @tags        ai-agents, get, crud, single-record
- */
+// 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"]
 export const get = createHandler(async (ctx, _body) => {
   const { id } = ctx.query || {}
 
@@ -115,9 +98,11 @@ export const get = createHandler(async (ctx, _body) => {
     throw new Error('Agent ID is required')
   }
 
-  const { data, error: err } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+
+  const { data, error: err } = await db
     .from('ai_agents')
-    .select(`*, ${joins.app}, ${joins.createdBy}`)
+    .select('*')
     .eq('id', id)
     .single()
 
@@ -125,23 +110,21 @@ export const get = createHandler(async (ctx, _body) => {
 
   return await sanitizeRecordData(ctx, data, 'ai_agent')
 })
-// ─── CHUNK_END: AI_AGENTS_GET ────────────────────────────────────────────────
-
-// ─── CHUNK_START: AI_AGENTS_CREATE ──────────────────────────────────────────────
-/**
- * @chunk-id    AI_AGENTS_CREATE_1_0_0
- * @version     1.0.0
- * @hash        355c8ceb1f33e033616480827141a2f33cde8e18fa4e9f9d94f4866af6fe66f6
- * @macro       AI Agent Create Handler
- * @micro       Creates new AI agent configuration with validation and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — Agent configuration data
- * @outputs     Inserted AI agent record
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB insert, audit logging]
- * @tags        ai-agents, create, crud, audit
- */
+// 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"]
 export const create = createHandler(async (ctx, body) => {
   const { app_id, name, description, agent_type, model_config, system_prompt, tools, capabilities, constraints, metadata } = body
 
@@ -181,23 +164,21 @@ export const create = createHandler(async (ctx, body) => {
 
   return data
 })
-// ─── CHUNK_END: AI_AGENTS_CREATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: AI_AGENTS_UPDATE ──────────────────────────────────────────────
-/**
- * @chunk-id    AI_AGENTS_UPDATE_1_0_0
- * @version     1.0.0
- * @hash        07e173626958a0ef032cc4c80719c49df5990756e08ecdb70a4168ab73544f10
- * @macro       AI Agent Update Handler
- * @micro       Updates AI agent with field validation and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — Agent updates including id
- * @outputs     Updated AI agent record
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB update, audit logging]
- * @tags        ai-agents, update, crud, audit
- */
+// 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"]
 export const update = createHandler(async (ctx, body) => {
   const id = body?.id || ctx.query?.id
   const { id: _bodyId, ...updates } = body || {}
@@ -210,7 +191,7 @@ export const update = createHandler(async (ctx, body) => {
     throw new Error('User context (person and account) required')
   }
 
-  const allowed = ['name', 'description', 'model_config', 'system_prompt', 'tools', 'capabilities', 'constraints', 'metadata', 'is_active']
+  const allowed = ['name', 'description', 'agent_type', 'model_config', 'system_prompt', 'tools', 'capabilities', 'constraints', 'metadata', 'is_active', 'app_id']
   const updateData: Record<string, any> = { updated_at: new Date().toISOString() }
   for (const key of allowed) {
     if (updates[key] !== undefined) updateData[key] = updates[key]
@@ -232,23 +213,21 @@ export const update = createHandler(async (ctx, body) => {
 
   return data
 })
-// ─── CHUNK_END: AI_AGENTS_UPDATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: AI_AGENTS_REMOVE ──────────────────────────────────────────────
-/**
- * @chunk-id    AI_AGENTS_REMOVE_1_0_0
- * @version     1.0.0
- * @hash        7d990350b55b85945cc2148908618d6cd1dad27d1fc8343eab6966bedd9d84fa
- * @macro       AI Agent Remove Handler
- * @micro       Hard-deletes AI agent with validation and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for DELETE)
- * @outputs     {success: true} — Success confirmation
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB delete, audit logging]
- * @tags        ai-agents, remove, crud, audit
- */
+// 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"]
 export const remove = createHandler(async (ctx, _body) => {
   const id = ctx.query?.id
 
@@ -278,25 +257,21 @@ export const remove = createHandler(async (ctx, _body) => {
 
   return { success: true }
 })
-// ─── CHUNK_END: AI_AGENTS_REMOVE ────────────────────────────────────────────────
-
-// ─── MAIN HANDLER ────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: AI_AGENTS_HANDLER ──────────────────────────────────────────────
-/**
- * @chunk-id    AI_AGENTS_HANDLER_1_0_0
- * @version     1.0.0
- * @hash        a49f4917dd07295e0ba9815bf929cccc5cffcbe4dcf6852aa4bd84d6cba1b690
- * @macro       AI Agents Router
- * @micro       Routes HTTP methods to appropriate CRUD handlers
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body for POST/PATCH operations
- * @outputs     Varies — Depends on routed handler (list/get/create/update/remove)
- * @depends-on  [createHandler, list, get, create, update, remove]
- * @depended-by [Netlify function routing]
- * @side-effects [Delegates to appropriate handler]
- * @tags        ai-agents, router, crud, netlify-function
- */
+// 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"]
 export const handler = createHandler(async (ctx, body) => {
   const { action } = ctx.query || {}
   const method = ctx.query?.method || 'GET'
@@ -320,4 +295,4 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error('Invalid action or method')
 })
-// ─── CHUNK_END: AI_AGENTS_HANDLER ────────────────────────────────────────────────
+// CIL[END chunk_id="ai-agents_handler_1784019432"]