Thread and State Lifecycle

Thread and State Lifecycle

Lifecycle State Machine

stateDiagram-v2
  [*] --> RouteResolved
  RouteResolved --> ScopeResolved: parse route/query/share
  ScopeResolved --> SessionStart: new chat request
  SessionStart --> ThreadReady: session start returns thread and canonical path
  ScopeResolved --> ThreadReady: has existing thread
  ScopeResolved --> ThreadBootstrap: fallback when thread missing during send
  ThreadBootstrap --> ThreadReady: createThread or ensureShareSessionThread
  ThreadReady --> Sending: user sends message
  Sending --> Streaming: /api/ai/stream connected
  Streaming --> AwaitingDecision: actions require HITL
  Streaming --> ThreadReady: done without HITL
  AwaitingDecision --> Resuming: approve/reject batch
  Resuming --> Streaming: /api/ai/resume stream
  Resuming --> ThreadReady: resume non-stream fallback
  ThreadReady --> RouteResolved: thread switch / new chat reset

Send Message Sequence (Canonical)

1. append pending user message ใน local state
2. materialize thread

• primary path: ใช้ startSession สำหรับ new chat/discovery start
• fallback path: ensureShareSessionThread หรือ createThread เมื่อ send แล้ว thread ยังไม่พร้อม

3. persist user message
4. create assistant placeholder (isStreaming=true)
5. call /api/ai/stream
6. stream chunks เข้าข้อความ placeholder
7. normalize/filter actions ตาม policy
8. persist final assistant message และ sync pending IDs

URL and Scope Canonicalization

flowchart LR
  A[Route enters with partial scope] --> B[load thread metadata]
  B --> C{missing scope?}
  C -- yes --> D[derive board/map/dashboard]
  D --> E[replace URL to canonical path]
  C -- no --> F[keep current URL]

Session Start Contract (New Chat)

• endpoint: POST /api/sessions/start
• request keys: projectId, agentId, optional scopeId, history, intent, source
• response keys หลัก: threadId, scopeKind, scopeId, canonicalPath, sessionVersion
• URL metadata ที่ใช้ sync รอบใหม่: scopeKind, scopeId, sv

HITL Batch Lifecycle

• decisions ถูก index ด้วย toolCallId
• staged states: approved / rejected / submitted
• resume รองรับ stream และ non-stream fallback
• หลัง resume ต้อง persist summary/actions เพื่อกันค้าง isStreaming

Failure and Recovery Rules

1. addMessage เจอ missing thread -> recover thread แล้ว retry
2. scope mismatch -> clear poisoned session และ redirect path ที่ปลอดภัย
3. resume stream ไม่จบสมบูรณ์ -> synthetic finalization + persist follow-up
4. analytics not ready -> block input จน dataset/template พร้อม
5. map thread insert เจอ legacy FK -> return map_scope_schema_outdated และต้อง apply migration ที่เกี่ยวข้อง