feat: thread-bound sessions via threadKey

packages/api/src/channels/agent-gateway.ts

@@ -28,6 +28,8 @@ export interface AgentTriggerPayload {
   summary?: string;
   /** Priority level */
   priority?: 'low' | 'normal' | 'high' | 'urgent';
+  /** Thread key for session routing (e.g., "pr:32") */
+  threadKey?: string;
   /** Additional metadata */
   metadata?: Record<string, unknown>;
 }

packages/api/src/data/models/memory.ts

@@ -82,6 +82,7 @@ export interface Session {
    * @deprecated Use studioId. Kept for backward compatibility during migration.
    */
   workspaceId?: string;
+  threadKey?: string;
   currentPhase?: string;
   startedAt: Date;
   endedAt?: Date;
@@ -97,6 +98,7 @@ export interface SessionCreateInput {
    * @deprecated Use studioId. Kept for backward compatibility during migration.
    */
   workspaceId?: string;
+  threadKey?: string;
   metadata?: Record<string, unknown>;
 }
 
@@ -151,6 +153,7 @@ export interface SessionRow {
   agent_id: string | null;
   studio_id: string | null;
   workspace_id: string | null;
+  thread_key: string | null;
   current_phase: string | null;
   started_at: string;
   ended_at: string | null;

packages/api/src/data/repositories/memory-repository.ts

@@ -198,6 +198,9 @@ export class MemoryRepository {
       // Backward compatibility for older server versions still reading workspace_id.
       insertData.workspace_id = scopedStudioId;
     }
+    if (input.threadKey) {
+      insertData.thread_key = input.threadKey;
+    }
 
     const { data, error } = await this.supabase
       .from('sessions')
@@ -345,6 +348,45 @@ export class MemoryRepository {
     return data ? this.rowToSession(data) : null;
   }
 
+  /**
+   * Get active session by threadKey for a user+agent, optionally scoped by studio.
+   * Returns the most recent active session with a matching thread_key, or null.
+   */
+  async getActiveSessionByThreadKey(
+    userId: string,
+    agentId: string,
+    threadKey: string,
+    studioId?: string | null
+  ): Promise<Session | null> {
+    let query = this.supabase
+      .from('sessions')
+      .select('*')
+      .eq('user_id', userId)
+      .eq('agent_id', agentId)
+      .eq('thread_key', threadKey)
+      .is('ended_at', null)
+      .order('started_at', { ascending: false })
+      .limit(1);
+
+    if (studioId !== undefined) {
+      if (studioId === null) {
+        query = query.is('studio_id', null);
+      } else {
+        query = query.eq('studio_id', studioId);
+      }
+    }
+
+    const { data, error } = await query.single();
+
+    if (error) {
+      if (error.code === 'PGRST116') return null;
+      logger.error('Failed to get active session by threadKey:', error);
+      throw new Error(`Failed to get active session by threadKey: ${error.message}`);
+    }
+
+    return data ? this.rowToSession(data) : null;
+  }
+
   /**
    * Get all active sessions for a user (without ended_at), ordered most recent first.
    * Used by bootstrap to return all active sessions so the client can pick the right one.
@@ -705,6 +747,7 @@ export class MemoryRepository {
       agentId: row.agent_id || undefined,
       studioId,
       workspaceId: studioId,
+      threadKey: row.thread_key || undefined,
       currentPhase: row.current_phase || undefined,
       startedAt: new Date(row.started_at),
       endedAt: row.ended_at ? new Date(row.ended_at) : undefined,