feat(memory): implement stability stage

Co-authored-by: multica-agent <github@multica.ai>

apps/web/server/api/v1/campaigns/[id].get.ts

@@ -40,7 +40,7 @@ export default defineEventHandler(async (event) => {
     const visibleMembers = members.map(member => ({ ...member, profile: profileById.get(String(member.user_id)) ?? null }))
     const visibleRounds = rounds.slice().reverse()
     const visibleRoundIds = visibleRounds.map(item => String(item.id))
-    const [intents, events, diceRolls] = await Promise.all([
+    const [intents, events, diceRolls, sceneStates, questStates, relationships, memories, storySummaries, auditEntries] = await Promise.all([
       round ? stageTwoDatabase<Array<Record<string, unknown>>>(
         `player_intents?select=id,round_id,member_id,character_id,action,ready,created_at,updated_at&round_id=eq.${String(round.id)}&order=created_at.asc`,
       ) : Promise.resolve([]),
@@ -50,8 +50,42 @@ export default defineEventHandler(async (event) => {
       visibleRoundIds.length ? stageTwoDatabase<Array<Record<string, unknown>>>(
         `dice_rolls?select=id,round_id,actor_id,target_id,check_kind,formula,rolls,kept,modifier,total,difficulty,success,created_at&round_id=in.(${visibleRoundIds.join(',')})&order=created_at.asc`,
       ) : Promise.resolve([]),
+      stageTwoDatabase<Array<Record<string, unknown>>>(
+        `scene_states?select=campaign_id,location_id,summary,active_entity_ids,tags,through_round,updated_at&campaign_id=eq.${campaignId}&limit=1`,
+      ),
+      stageTwoDatabase<Array<Record<string, unknown>>>(
+        `quest_states?select=campaign_id,quest_entity_id,status,summary,tags,through_round,updated_at&campaign_id=eq.${campaignId}&order=updated_at.desc`,
+      ),
+      stageTwoDatabase<Array<Record<string, unknown>>>(
+        `relationships?select=source_entity_id,target_entity_id,score,notes&campaign_id=eq.${campaignId}&order=score.desc&limit=30`,
+      ),
+      stageTwoDatabase<Array<Record<string, unknown>>>(
+        `memories?select=id,round_id,summary,importance,tags,entity_ids,created_at&campaign_id=eq.${campaignId}&order=importance.desc,created_at.desc&limit=20`,
+      ),
+      stageTwoDatabase<Array<Record<string, unknown>>>(
+        `story_summaries?select=id,through_round,summary,created_at&campaign_id=eq.${campaignId}&order=through_round.desc&limit=1`,
+      ),
+      access.owner ? stageTwoDatabase<Array<Record<string, unknown>>>(
+        `audit_entries?select=id,actor_id,action,entity_type,entity_id,before_state,after_state,created_at&campaign_id=eq.${campaignId}&order=created_at.desc&limit=50`,
+      ) : Promise.resolve([]),
     ])
-    return { campaign, world: worlds[0] ?? null, members: visibleMembers, characters, round, rounds: visibleRounds, intents, events: events.slice().reverse(), diceRolls }
+    return {
+      campaign,
+      world: worlds[0] ?? null,
+      members: visibleMembers,
+      characters,
+      round,
+      rounds: visibleRounds,
+      intents,
+      events: events.slice().reverse(),
+      diceRolls,
+      sceneState: sceneStates[0] ?? null,
+      activeGoals: questStates.filter(quest => quest.status === 'active'),
+      relationships,
+      memories,
+      storySummary: storySummaries[0] ?? null,
+      auditEntries,
+    }
   } catch (error) {
     stageTwoApiError(error)
   }

apps/web/server/api/v1/campaigns/[id]/characters/[characterId].patch.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod'
+import {
+  requireCampaignAccess,
+  requireStageTwoSafeText,
+  requireStageTwoUser,
+  stageTwoApiError,
+  stageTwoRpc,
+  stageTwoUuid,
+} from '~/server/utils/stage-two-supabase'
+
+const BodySchema = z.object({
+  hp: z.number().int().min(0).optional(),
+  inventory: z.array(z.string().trim().min(1).max(120)).max(50).optional(),
+  statuses: z.array(z.string().trim().min(1).max(80)).max(12).optional(),
+  reason: z.string().trim().min(3).max(500),
+}).strict().refine(body => body.hp !== undefined || body.inventory !== undefined || body.statuses !== undefined, {
+  message: 'At least one state field is required.',
+})
+
+export default defineEventHandler(async (event) => {
+  try {
+    const user = await requireStageTwoUser(event)
+    const campaignId = stageTwoUuid(getRouterParam(event, 'id'), 'campaign id')
+    const characterId = stageTwoUuid(getRouterParam(event, 'characterId'), 'character id')
+    await requireCampaignAccess(campaignId, user.id, true)
+    const body = BodySchema.parse(await readBody(event))
+    requireStageTwoSafeText([body.reason, ...(body.inventory ?? []), ...(body.statuses ?? [])].join('\n'))
+    const { reason, ...patch } = body
+    const state = await stageTwoRpc<Record<string, unknown>>('stage_six_adjust_character_state', {
+      p_campaign_id: campaignId,
+      p_owner_id: user.id,
+      p_character_id: characterId,
+      p_patch: patch,
+      p_reason: reason,
+    })
+    return { characterId, state }
+  } catch (error) {
+    stageTwoApiError(error)
+  }
+})

apps/web/server/api/v1/campaigns/[id]/characters/suggest.post.ts

@@ -5,6 +5,8 @@ import {
   requireCampaignAccess,
   requireStageTwoSafeText,
   requireStageTwoUser,
+  stageSixConsumeAiQuota,
+  stageSixRecordAiUsage,
   stageTwoApiError,
   stageTwoDatabase,
   stageTwoUuid,
@@ -48,8 +50,10 @@ export default defineEventHandler(async (event) => {
       jsonSchema: CharacterDraftSchema.toJSONSchema(),
     })
 
+    await stageSixConsumeAiQuota(user.id, campaignId, 'character-draft')
     const controller = new AbortController()
     const timeout = setTimeout(() => controller.abort(), 30_000)
+    const startedAt = Date.now()
     let response: Response
     try {
       response = await fetch(completion.endpoint, {
@@ -62,10 +66,14 @@ export default defineEventHandler(async (event) => {
       clearTimeout(timeout)
     }
     if (!response.ok) throw createError({ statusCode: 502, statusMessage: 'The character coauthor is temporarily unavailable.' })
+    const payload = await response.json()
+    await stageSixRecordAiUsage({
+      userId: user.id, campaignId, requestKind: 'character-draft', completion, payload, latencyMs: Date.now() - startedAt,
+    }).catch(error => console.error('[web] could not record character draft usage:', error))
 
     let character
     try {
-      character = CharacterDraftSchema.parse(parseJsonCompletion(await response.json()))
+      character = CharacterDraftSchema.parse(parseJsonCompletion(payload))
     } catch {
       throw createError({ statusCode: 502, statusMessage: 'The coauthor returned an invalid character draft.' })
     }

apps/web/server/api/v1/campaigns/[id]/rounds/[roundId]/retry.post.ts

@@ -1,4 +1,4 @@
-import { requireCampaignAccess, requireStageTwoUser, stageTwoApiError, stageTwoDatabase, stageTwoRpc, stageTwoUuid } from '~/server/utils/stage-two-supabase'
+import { requireCampaignAccess, requireStageTwoUser, stageSixConsumeAiQuota, stageTwoApiError, stageTwoDatabase, stageTwoRpc, stageTwoUuid } from '~/server/utils/stage-two-supabase'
 
 export default defineEventHandler(async (event) => {
   try {
@@ -11,6 +11,7 @@ export default defineEventHandler(async (event) => {
     )
     if (!rounds[0]) throw createError({ statusCode: 404, statusMessage: 'Round not found.' })
     if (rounds[0].status !== 'failed') throw createError({ statusCode: 409, statusMessage: 'Only a failed round can be retried.' })
+    await stageSixConsumeAiQuota(user.id, campaignId, 'retry-round')
     const jobId = await stageTwoRpc<string>('stage_two_retry_failed_round', {
       p_round_id: roundId,
       p_owner_id: user.id,