spine-framework 0.3.124 → 0.3.126

package/.framework/functions/prompt-configs.ts

@@ -1,59 +1,29 @@
-/**
- * @module prompt-configs
- * @audience core-contributor
- * @layer api-handler
- * @stability stable
- *
- * CRUD API for the `prompt_configs` table. Prompt configs define LLM inference
- * parameters: system prompts, context templates, model selection, temperature,
- * confidence thresholds, escalation rules, tool access, and knowledge sources.
- * They are referenced by AI agents at inference time via `agent-runner.ts`.
- *
- * **Routed by:** `GET/POST/PATCH/DELETE /.netlify/functions/prompt-configs`
- *
- * **Standard CRUD routing:**
- * | method | condition | handler |
- * |--------|-----------|---------|
- * | GET    | ?id       | get     |
- * | GET    | (default) | list    |
- * | POST   | —         | create  |
- * | PATCH  | —         | update  |
- * | DELETE | —         | remove  |
- *
- * **Authorization:** All operations use `ctx.db` (RLS-scoped). Account context
- * required for writes.
- *
- * INVARIANT: `remove` is a hard delete.
- * INVARIANT: `update` only patches the explicit allowlist of fields.
- * INVARIANT: `model` defaults to 'gpt-4o', `temperature` to 0.7,
- *   `max_tokens` to 4000 if not specified on create.
- *
- * @seeAlso agent-runner.ts (resolveAgentConfig reads prompt_configs)
- * @seeAlso ai-agents.ts (ai_agents reference prompt_config_id)
- * @seeAlso audit.ts (emitLog for prompt_config.* events)
- */
-
 import { createHandler } from './_shared/middleware'
 import { emitLog } from './_shared/audit'
 import { sanitizeRecordData } from './_shared/permissions'
+import { adminDb } from './_shared/db'
+import { isSystemAdmin } from './_shared/principal'
+
+
+
 
-// ─── HANDLERS ─────────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: PROMPT_CONFIGS_LIST ──────────────────────────────────────────────
-/**
- * @chunk-id    PROMPT_CONFIGS_LIST_1_0_0
- * @version     1.0.0
- * @hash        177c1ca02d205ad820b03fef84d2667ddde4eaa8a2aa82fbf3ee58d4f68890aa
- * @macro       Prompt Configs List Handler
- * @micro       Lists prompt configs with filtering and sanitization
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     Array of sanitized prompt_config records with app/createdBy joins
- * @depends-on  [createHandler, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB queries, permission sanitization]
- * @tags        prompt-configs, list, crud, pagination
- */
+
+
+// CIL[BEGIN chunk_id="prompt-configs_module_header_1783932909" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Lists prompt configs with filtering and sanitization"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle prompt config listing with filters"]
+// CIL[DOC-CONTEXT module="prompt-configs" layer="api-handler" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/db.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="ctx, _body" outputs="Array of sanitized prompt configs" errors="Throws on DB errors" side_effects="Database queries, permission sanitization"]
+// CIL[DOC-MICRO logic_summary="Filters by model/active status, applies sanitization" 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/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/db.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 { model, is_active, limit = 100, offset = 0 } = ctx.query || {}
 
@@ -61,13 +31,11 @@ export const list = createHandler(async (ctx, _body) => {
     throw new Error('Account context required')
   }
 
-  let query = ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+
+  let query = db
     .from('prompt_configs')
-    .select(`
-      *,
-      app:apps(id, slug, name),
-      created_by_person:people!prompt_configs_created_by_fkey(id, full_name, email)
-    `)
+    .select('*')
     .order('name')
 
   if (model) {
@@ -91,23 +59,21 @@ export const list = createHandler(async (ctx, _body) => {
 
   return sanitized
 })
-// ─── CHUNK_END: PROMPT_CONFIGS_LIST ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PROMPT_CONFIGS_GET ──────────────────────────────────────────────
-/**
- * @chunk-id    PROMPT_CONFIGS_GET_1_0_0
- * @version     1.0.0
- * @hash        234cc28b4e9fba9333a221ac01d175bafaf93681221f182d6925df84caf90348
- * @macro       Prompt Config Get Handler
- * @micro       Returns single prompt config record with joins and sanitization
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     Sanitized prompt_config record with app/createdBy joins
- * @depends-on  [createHandler, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB single row query, permission sanitization]
- * @tags        prompt-configs, get, crud, single-record
- */
+// CIL[END chunk_id="prompt-configs_module_header_1783932909"]
+// CIL[BEGIN chunk_id="prompt-configs_get_1783932909" type="function" identity="get" parent="none"]
+// CIL[DOC-MACRO purpose="Retrieves single prompt config by ID with sanitization"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle individual prompt config retrieval"]
+// CIL[DOC-CONTEXT module="prompt-configs" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Sanitized prompt config record" errors="Throws if ID missing or DB error" side_effects="Database query, permission sanitization"]
+// CIL[DOC-MICRO logic_summary="Fetches config 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, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/components/ui/dialog.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"]
 export const get = createHandler(async (ctx, _body) => {
   const { id } = ctx.query || {}
 
@@ -115,13 +81,10 @@ export const get = createHandler(async (ctx, _body) => {
     throw new Error('Config 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('prompt_configs')
-    .select(`
-      *,
-      app:apps(id, slug, name),
-      created_by_person:people!prompt_configs_created_by_fkey(id, full_name, email)
-    `)
+    .select('*')
     .eq('id', id)
     .single()
 
@@ -129,25 +92,23 @@ export const get = createHandler(async (ctx, _body) => {
 
   return await sanitizeRecordData(ctx, data, 'prompt_config')
 })
-// ─── CHUNK_END: PROMPT_CONFIGS_GET ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PROMPT_CONFIGS_CREATE ──────────────────────────────────────────────
-/**
- * @chunk-id    PROMPT_CONFIGS_CREATE_1_0_0
- * @version     1.0.0
- * @hash        e4aeda63ad485550140a44aa281020c9a6fc966da444d135281d869e053c5e6c
- * @macro       Prompt Config Create Handler
- * @micro       Creates prompt config with validation and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — Prompt config data including name, slug, and optional fields
- * @outputs     Inserted prompt_config record
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB insert, audit logging]
- * @tags        prompt-configs, create, crud, audit
- */
+// CIL[END chunk_id="prompt-configs_get_1783932909"]
+// CIL[BEGIN chunk_id="prompt-configs_create_1783932909" type="function" identity="create" parent="none"]
+// CIL[DOC-MACRO purpose="Creates new prompt config with validation and defaults"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle prompt config creation with security"]
+// CIL[DOC-CONTEXT module="prompt-configs" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Created prompt config record" errors="Throws on validation or DB errors" side_effects="Database insert, audit logging"]
+// CIL[DOC-MICRO logic_summary="Validates required fields, sets defaults, creates config" 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: 3. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, .framework/src/components/ui/dialog.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 3. Total affected: 4."]
+// 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, slug, system_prompt, context_template, model, temperature, max_tokens,
+  const { app_id, name, slug, description, system_prompt, context_template, model, temperature, max_tokens,
     is_multi_turn, max_history_messages, confidence_threshold, escalation_action, escalation_target,
     output_mode, output_field, requires_review, knowledge_sources, available_tools, tool_constraints,
     metadata } = body
@@ -167,6 +128,7 @@ export const create = createHandler(async (ctx, body) => {
       account_id: ctx.accountId,
       name,
       slug,
+      description: description || null,
       system_prompt: system_prompt || null,
       context_template: context_template || null,
       model: model || 'gpt-4o',
@@ -183,8 +145,7 @@ export const create = createHandler(async (ctx, body) => {
       knowledge_sources: knowledge_sources || [],
       available_tools: available_tools || [],
       tool_constraints: tool_constraints || {},
-      metadata: metadata || {},
-      created_by: ctx.principal?.id
+      metadata: metadata || {}
     })
     .select()
     .single()
@@ -198,23 +159,21 @@ export const create = createHandler(async (ctx, body) => {
 
   return data
 })
-// ─── CHUNK_END: PROMPT_CONFIGS_CREATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PROMPT_CONFIGS_UPDATE ──────────────────────────────────────────────
-/**
- * @chunk-id    PROMPT_CONFIGS_UPDATE_1_0_0
- * @version     1.0.0
- * @hash        32985018c871c4d8b6faf93f817c33e8b9f65e6dbae5cdb0df37fa16bf7b2db1
- * @macro       Prompt Config Update Handler
- * @micro       Updates prompt config with field allowlist and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — Prompt config updates including id and updatable fields
- * @outputs     Updated prompt_config record
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB update, audit logging]
- * @tags        prompt-configs, update, crud, audit
- */
+// CIL[END chunk_id="prompt-configs_create_1783932909"]
+// CIL[BEGIN chunk_id="prompt-configs_update_1783932909" type="function" identity="update" parent="none"]
+// CIL[DOC-MACRO purpose="Updates prompt config with field allowlist validation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle prompt config updates with security"]
+// CIL[DOC-CONTEXT module="prompt-configs" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/db.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Updated prompt config record" errors="Throws on validation or DB errors" side_effects="Database update, audit logging"]
+// CIL[DOC-MICRO logic_summary="Updates allowed fields, maintains audit trail" 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: 9. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/db.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/components/ui/dialog.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 9. Total affected: 11."]
+// 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 || {}
@@ -223,7 +182,7 @@ export const update = createHandler(async (ctx, body) => {
     throw new Error('Config ID is required')
   }
 
-  const allowed = ['name', 'slug', 'system_prompt', 'context_template', 'model', 'temperature',
+  const allowed = ['name', 'slug', 'description', 'app_id', 'system_prompt', 'context_template', 'model', 'temperature',
     'max_tokens', 'is_multi_turn', 'max_history_messages', 'confidence_threshold',
     'escalation_action', 'escalation_target', 'output_mode', 'output_field', 'requires_review',
     'knowledge_sources', 'available_tools', 'tool_constraints', 'metadata', 'is_active']
@@ -248,23 +207,21 @@ export const update = createHandler(async (ctx, body) => {
 
   return data
 })
-// ─── CHUNK_END: PROMPT_CONFIGS_UPDATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: PROMPT_CONFIGS_REMOVE ──────────────────────────────────────────────
-/**
- * @chunk-id    PROMPT_CONFIGS_REMOVE_1_0_0
- * @version     1.0.0
- * @hash        2d6cdf4f067fe7259c1fb3d07c5928df36a2395424772a85a7d474072d883b84
- * @macro       Prompt Config Remove Handler
- * @micro       Hard-deletes prompt config with audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for DELETE)
- * @outputs     {success: true} — Confirmation of successful deletion
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB delete, audit logging]
- * @tags        prompt-configs, remove, delete, audit
- */
+// CIL[END chunk_id="prompt-configs_update_1783932909"]
+// CIL[BEGIN chunk_id="prompt-configs_remove_1783932909" type="function" identity="remove" parent="none"]
+// CIL[DOC-MACRO purpose="Hard deletes prompt config with audit logging"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle prompt config deletion with audit trail"]
+// CIL[DOC-CONTEXT module="prompt-configs" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/db.ts\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="{success: true}" errors="Throws if ID missing or DB error" side_effects="Database delete, audit logging"]
+// CIL[DOC-MICRO logic_summary="Hard deletes config, maintains audit trail" 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/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/db.ts, .framework/src/components/ui/table-primitives.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"]
 export const remove = createHandler(async (ctx, _body) => {
   const id = ctx.query?.id
 
@@ -294,25 +251,21 @@ export const remove = createHandler(async (ctx, _body) => {
 
   return { success: true }
 })
-// ─── CHUNK_END: PROMPT_CONFIGS_REMOVE ────────────────────────────────────────────────
-
-// ─── MAIN HANDLER ────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: PROMPT_CONFIGS_HANDLER ──────────────────────────────────────────────
-/**
- * @chunk-id    PROMPT_CONFIGS_HANDLER_1_0_0
- * @version     1.0.0
- * @hash        a49f4917dd07295e0ba9815bf929cccc5cffcbe4dcf6852aa4bd84d6cba1b690
- * @macro       Prompt Configs Router
- * @micro       Routes HTTP methods to appropriate prompt config 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        prompt-configs, router, crud, netlify-function
- */
+// CIL[END chunk_id="prompt-configs_remove_1783932909"]
+// CIL[BEGIN chunk_id="prompt-configs_handler_1783932909" type="function" identity="handler" parent="none"]
+// CIL[DOC-MACRO purpose="Routes HTTP methods to prompt config handlers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle request routing for prompt config CRUD"]
+// CIL[DOC-CONTEXT module="prompt-configs" layer="api-handler" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Varies by handler" errors="Throws on unsupported methods" side_effects="Delegates to appropriate handler"]
+// CIL[DOC-MICRO logic_summary="Routes based on method, delegates to CRUD handlers" 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/cortex/functions/custom_cil-embeddings.ts, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/table-primitives.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"]
 export const handler = createHandler(async (ctx, body) => {
   const { action } = ctx.query || {}
   const method = ctx.query?.method || 'GET'
@@ -336,4 +289,4 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error('Invalid action or method')
 })
-// ─── CHUNK_END: PROMPT_CONFIGS_HANDLER ────────────────────────────────────────────────
+// CIL[END chunk_id="prompt-configs_handler_1783932909"]