qlogicagent 2.13.4 → 2.13.5

package/dist/cli/handlers/session-handler.js

@@ -0,0 +1,833 @@
+/**
+ * Session & Thread handlers - uses SessionLocator for all path resolution.
+ *
+ * Handles: thread.create, thread.list, session.create, session.resolve,
+ *          session.list, session.get, session.getMessages, session.update,
+ *          session.delete, session.deleteAll, session.archive, session.resume,
+ *          session.getInfo, session.switchProject, session.getState
+ *
+ * Key invariant: every session operation resolves storage path via projectId,
+ * never via the global `currentProjectRoot`. Sessions are immutably bound
+ * to a project at creation time.
+ */
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as projectStore from "../../runtime/infra/project-store.js";
+import { SessionState } from "../../runtime/session/session-state.js";
+import { SessionLocator } from "../../runtime/session/session-locator.js";
+import { createMemoryPrefetchState } from "../../runtime/hooks/memory-hooks.js";
+import { listSessions, loadSessionForResume, updateSessionMetadata, deleteSession, getSessionMetadata, } from "../../runtime/session/session-persistence.js";
+import { maybeAutoSplitGroupSession } from "../../runtime/session/group-session-split.js";
+import { getUserAgentHome, getUserSettingsPath, getProjectSessionsRoot } from "../../runtime/infra/agent-paths.js";
+import { AGENT_RPC_ERROR_CODES } from "../../protocol/wire/index.js";
+import { SessionQueryService } from "../session-query-service.js";
+const locator = new SessionLocator();
+const sessionQueries = new SessionQueryService(locator);
+function errorMessage(err, fallback = "Unknown error") {
+    return err instanceof Error ? err.message : fallback;
+}
+function safeSessionId(sessionId) {
+    return sessionId.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+function resolveSessionWorkspaceDir(host, sessionId, projectId) {
+    return sessionQueries.resolveSessionWorkspaceDir(host, sessionId, projectId);
+}
+// Thread handlers
+export function handleThreadCreate(msg) {
+    const params = msg.params;
+    const threadId = params?.id ?? randomUUID();
+    this.log(`[thread.create] id=${threadId} title=${params?.title ?? "(none)"}`);
+    // Set workdir if provided
+    if (params?.cwd && typeof params.cwd === "string") {
+        this.setActiveWorkdir(params.cwd);
+    }
+    // Initialize session state for this thread
+    this.currentSessionId = threadId;
+    this.sessionState = new SessionState(threadId);
+    this.sessionTaskDomain = undefined;
+    this.memoryPrefetchState = createMemoryPrefetchState();
+    // Enable idle dream scheduling (self-managed by agent)
+    this.enableIdleDream();
+    if (msg.id !== undefined) {
+        this.sendResponse(msg.id, {
+            id: threadId,
+            title: params?.title,
+            status: "active",
+            createdAt: new Date().toISOString(),
+        });
+    }
+}
+export async function handleThreadList(msg) {
+    const params = msg.params;
+    const limit = params?.limit ?? 20;
+    try {
+        const threads = await sessionQueries.listThreads(limit, params?.projectId);
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, { threads });
+        }
+    }
+    catch (err) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INTERNAL_ERROR,
+                message: `Failed to list threads: ${errorMessage(err)}`,
+            });
+        }
+    }
+}
+// Session CRUD handlers
+export async function handleSessionCreate(msg) {
+    const params = msg.params;
+    const sessionId = params?.sessionId ?? randomUUID();
+    try {
+        const targetProjectId = params?.projectId ?? sessionQueries.getActiveProjectId();
+        const storageRoot = sessionQueries.getProjectWorkspaceDir(targetProjectId);
+        await updateSessionMetadata(sessionId, {
+            sessionId,
+            title: params?.title,
+            type: params?.type,
+            ownerPlatform: params?.ownerPlatform,
+            ownerId: params?.ownerId,
+            groupKey: params?.groupKey,
+            groupName: params?.groupName,
+            groupPlatform: params?.groupPlatform,
+            projectId: targetProjectId,
+        }, storageRoot);
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, { sessionId, title: params?.title });
+        }
+    }
+    catch (err) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INTERNAL_ERROR,
+                message: `Failed to create session: ${errorMessage(err)}`,
+            });
+        }
+    }
+}
+export async function handleSessionResolve(msg) {
+    const params = msg.params;
+    if (msg.id === undefined)
+        return;
+    const platform = params?.platform ?? "desktop";
+    const chatId = params?.chatId;
+    const chatType = params?.chatType;
+    const userId = params?.userId ?? "local";
+    try {
+        // Desktop: Gateway must pass projectId; no filesystem scan
+        if (platform === "desktop" && chatId) {
+            const targetProjectId = params?.projectId ?? sessionQueries.getActiveProjectId();
+            const workspaceDir = sessionQueries.getProjectWorkspaceDir(targetProjectId);
+            const entries = await listSessions(500, workspaceDir);
+            const found = entries.find((s) => s.sessionId === chatId);
+            if (found) {
+                const meta = getSessionMetadata(chatId, workspaceDir);
+                this.sendResponse(msg.id, {
+                    sessionId: chatId,
+                    title: meta?.title ?? found.title,
+                    type: meta?.type ?? found.type ?? "personal",
+                    agentId: meta?.agentId,
+                    ownerPlatform: meta?.ownerPlatform,
+                    ownerId: meta?.ownerId ?? userId,
+                    groupKey: meta?.groupKey,
+                    groupPlatform: meta?.groupPlatform,
+                    groupName: meta?.groupName,
+                    projectId: meta?.projectId ?? targetProjectId,
+                });
+                return;
+            }
+            // Not found - create new session in target project
+            await updateSessionMetadata(chatId, {
+                sessionId: chatId,
+                type: "personal",
+                ownerPlatform: platform === "desktop" ? undefined : platform,
+                ownerId: userId,
+                projectId: targetProjectId,
+            }, workspaceDir);
+            this.sendResponse(msg.id, {
+                sessionId: chatId,
+                type: "personal",
+                ownerPlatform: platform === "desktop" ? undefined : platform,
+                ownerId: userId,
+                projectId: targetProjectId,
+            });
+            return;
+        }
+        // Group chat: match by groupKey across all projects
+        if (chatType === "group" && chatId && platform) {
+            const groupKey = `group:${platform}:${chatId}`;
+            const allProjects = projectStore.listProjects();
+            for (const project of allProjects) {
+                if (!project.workspaceDir)
+                    continue;
+                const entries = await listSessions(500, project.workspaceDir);
+                const found = entries.find((s) => s.groupKey === groupKey && !s.sealedAt && !s.archivedAt);
+                if (found) {
+                    // Check idle timeout - auto-split if group session has been idle too long
+                    const meta = getSessionMetadata(found.sessionId, project.workspaceDir);
+                    if (meta) {
+                        const splitResult = await maybeAutoSplitGroupSession(meta, project.workspaceDir);
+                        if (splitResult.split) {
+                            this.sendResponse(msg.id, {
+                                sessionId: splitResult.activeSessionId,
+                                title: undefined, // New session, no title yet
+                                type: "group",
+                                ownerPlatform: meta.ownerPlatform,
+                                ownerId: userId,
+                                groupKey,
+                                groupPlatform: platform,
+                                groupName: params?.groupName,
+                                projectId: project.id,
+                                previousSessionId: splitResult.sealedSessionId,
+                            });
+                            return;
+                        }
+                    }
+                    this.sendResponse(msg.id, {
+                        sessionId: found.sessionId,
+                        title: found.title,
+                        type: "group",
+                        ownerPlatform: meta?.ownerPlatform,
+                        ownerId: userId,
+                        groupKey,
+                        groupPlatform: platform,
+                        groupName: params?.groupName,
+                        projectId: project.id,
+                    });
+                    return;
+                }
+            }
+        }
+        // Not found: create a new channel-bound session.
+        if (chatType !== "group" && platform !== "desktop" && userId) {
+            const targetPersonalProject = params?.projectId
+                ? projectStore.getProjectById(params.projectId)
+                : projectStore.getDefaultProject();
+            const allProjects = targetPersonalProject ? [targetPersonalProject] : [];
+            for (const project of allProjects) {
+                if (!project.workspaceDir)
+                    continue;
+                const entries = await listSessions(500, project.workspaceDir);
+                for (const entry of entries) {
+                    if (entry.type !== "personal" || entry.sealedAt || entry.archivedAt)
+                        continue;
+                    const meta = getSessionMetadata(entry.sessionId, project.workspaceDir);
+                    if (meta?.archivedAt)
+                        continue;
+                    if (meta?.ownerPlatform !== platform || meta.ownerId !== userId)
+                        continue;
+                    this.sendResponse(msg.id, {
+                        sessionId: meta.sessionId,
+                        title: meta.title ?? entry.title,
+                        type: "personal",
+                        ownerPlatform: meta.ownerPlatform,
+                        ownerId: meta.ownerId,
+                        projectId: meta.projectId ?? project.id,
+                    });
+                    return;
+                }
+            }
+        }
+        const sessionId = randomUUID();
+        const targetProjectId = params?.projectId
+            ?? (chatType === "group" ? sessionQueries.getActiveProjectId() : sessionQueries.getDefaultProjectId());
+        const createRoot = sessionQueries.getProjectWorkspaceDir(targetProjectId);
+        const groupKey = chatType === "group" ? `group:${platform}:${chatId}` : undefined;
+        const initialTitle = cleanSessionTitle(params?.title);
+        await updateSessionMetadata(sessionId, {
+            sessionId,
+            title: initialTitle,
+            type: chatType === "group" ? "group" : "personal",
+            ownerPlatform: chatType === "group" || platform === "desktop" ? undefined : platform,
+            ownerId: userId,
+            groupKey,
+            groupPlatform: chatType === "group" ? platform : undefined,
+            groupName: params?.groupName,
+            projectId: targetProjectId,
+        }, createRoot);
+        this.sendResponse(msg.id, {
+            sessionId,
+            title: initialTitle,
+            type: chatType === "group" ? "group" : "personal",
+            ownerPlatform: chatType === "group" || platform === "desktop" ? undefined : platform,
+            ownerId: userId,
+            groupKey,
+            groupPlatform: chatType === "group" ? platform : undefined,
+            groupName: params?.groupName,
+            projectId: targetProjectId,
+        });
+    }
+    catch (err) {
+        this.sendResponse(msg.id, undefined, {
+            code: AGENT_RPC_ERROR_CODES.INTERNAL_ERROR,
+            message: `Failed to resolve session: ${errorMessage(err)}`,
+        });
+    }
+}
+function cleanSessionTitle(title) {
+    const cleaned = title?.replace(/\s+/g, " ").trim();
+    if (!cleaned)
+        return undefined;
+    return cleaned.slice(0, 40);
+}
+export async function handleSessionList(msg) {
+    const params = msg.params;
+    const limit = params?.limit ?? 50;
+    try {
+        let entries;
+        if (params?.projectId) {
+            const project = projectStore.getProjectById(params.projectId);
+            if (!project) {
+                // Project not found (deleted/invalid) - return empty list, not crash
+                if (msg.id !== undefined)
+                    this.sendResponse(msg.id, { sessions: [] });
+                return;
+            }
+            const workspaceDir = project.workspaceDir;
+            entries = await listSessions(limit * 2, workspaceDir);
+            // Filter by actual metadata projectId (handles shared workspaceDir)
+            entries = entries.filter((e) => e.projectId === params.projectId);
+            for (const e of entries)
+                e.projectId = params.projectId;
+        }
+        else {
+            const projects = projectStore.listProjects();
+            const seen = new Set();
+            const allEntries = [];
+            for (const project of projects) {
+                if (!project.workspaceDir)
+                    continue;
+                const projectEntries = await listSessions(limit, project.workspaceDir);
+                for (const e of projectEntries) {
+                    if (seen.has(e.sessionId))
+                        continue;
+                    if (!e.projectId)
+                        continue; // Skip orphaned sessions with no project binding
+                    seen.add(e.sessionId);
+                    // Keep metadata's projectId (don't overwrite) - handles shared workspaceDirs
+                    allEntries.push(e);
+                }
+            }
+            allEntries.sort((a, b) => (a.lastActiveAt > b.lastActiveAt ? -1 : a.lastActiveAt < b.lastActiveAt ? 1 : 0));
+            entries = allEntries;
+        }
+        if (params?.archived === true) {
+            entries = entries.filter((s) => s.archivedAt != null);
+        }
+        else if (params?.archived === false) {
+            entries = entries.filter((s) => s.archivedAt == null);
+        }
+        const sessions = entries.slice(0, limit).map((s) => ({
+            sessionId: s.sessionId,
+            title: s.title,
+            type: s.type ?? "personal",
+            agentId: s.agentId,
+            lastActiveAt: s.lastActiveAt,
+            pinnedAt: s.pinnedAt ?? null,
+            archivedAt: s.archivedAt ?? null,
+            sealedAt: s.sealedAt ?? null,
+            projectId: s.projectId,
+            previousSessionId: s.previousSessionId ?? null,
+            carryoverSummary: s.carryoverSummary ?? null,
+        }));
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, { sessions });
+        }
+    }
+    catch (err) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INTERNAL_ERROR,
+                message: `Failed to list sessions: ${errorMessage(err)}`,
+            });
+        }
+    }
+}
+export async function handleSessionGet(msg) {
+    const params = msg.params;
+    if (!params?.sessionId) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INVALID_PARAMS,
+                message: "Missing required param: sessionId",
+            });
+        }
+        return;
+    }
+    try {
+        const workspaceDir = resolveSessionWorkspaceDir(this, params.sessionId, params.projectId);
+        const entries = await listSessions(500, workspaceDir);
+        const found = entries.find((s) => s.sessionId === params.sessionId);
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, {
+                session: found ? {
+                    sessionId: found.sessionId,
+                    title: found.title,
+                    type: found.type,
+                    lastActiveAt: found.lastActiveAt,
+                    pinnedAt: found.pinnedAt ?? null,
+                    archivedAt: found.archivedAt ?? null,
+                    projectId: found.projectId,
+                } : null,
+            });
+        }
+    }
+    catch (err) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INTERNAL_ERROR,
+                message: `Failed to get session: ${errorMessage(err)}`,
+            });
+        }
+    }
+}
+export async function handleSessionGetMessages(msg) {
+    const params = msg.params;
+    if (!params?.sessionId) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INVALID_PARAMS,
+                message: "Missing required param: sessionId",
+            });
+        }
+        return;
+    }
+    try {
+        const workspaceDir = resolveSessionWorkspaceDir(this, params.sessionId, params.projectId);
+        const session = await loadSessionForResume(params.sessionId, workspaceDir, { includeDisplayMetadata: true });
+        if (!session) {
+            if (msg.id !== undefined) {
+                this.sendResponse(msg.id, { messages: [], total: 0 });
+            }
+            return;
+        }
+        const allMessages = session.messages;
+        const limit = params.limit && params.limit > 0 ? params.limit : allMessages.length;
+        const sliced = allMessages.slice(-limit);
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, { messages: sliced, total: allMessages.length });
+        }
+    }
+    catch (err) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INTERNAL_ERROR,
+                message: `Failed to get messages: ${errorMessage(err)}`,
+            });
+        }
+    }
+}
+export async function handleSessionUpdate(msg) {
+    const params = msg.params;
+    if (!params?.sessionId) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INVALID_PARAMS,
+                message: "Missing required param: sessionId",
+            });
+        }
+        return;
+    }
+    try {
+        const workspaceDir = resolveSessionWorkspaceDir(this, params.sessionId, params.projectId);
+        const result = await updateSessionMetadata(params.sessionId, {
+            ...(params.title !== undefined ? { title: params.title } : {}),
+            ...(params.pinnedAt !== undefined ? { pinnedAt: params.pinnedAt } : {}),
+            ...(params.archivedAt !== undefined ? { archivedAt: params.archivedAt } : {}),
+        }, workspaceDir);
+        if (result) {
+            this.sendNotification("session.info", {
+                sessionId: params.sessionId,
+                title: result.title,
+                pinnedAt: result.pinnedAt ?? null,
+                archivedAt: result.archivedAt ?? null,
+                projectId: params.projectId || undefined,
+            });
+        }
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, { ok: result !== null });
+        }
+    }
+    catch (err) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INTERNAL_ERROR,
+                message: `Failed to update session: ${errorMessage(err)}`,
+            });
+        }
+    }
+}
+export async function handleSessionDelete(msg) {
+    const params = msg.params;
+    if (!params?.sessionId) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INVALID_PARAMS,
+                message: "Missing required param: sessionId",
+            });
+        }
+        return;
+    }
+    if (!params.projectId) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INVALID_PARAMS,
+                message: "Missing required param: projectId",
+            });
+        }
+        return;
+    }
+    try {
+        const workspaceDir = resolveSessionWorkspaceDir(this, params.sessionId, params.projectId);
+        await deleteSession(params.sessionId, workspaceDir);
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, { ok: true });
+        }
+    }
+    catch (err) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INTERNAL_ERROR,
+                message: `Failed to delete session: ${errorMessage(err)}`,
+            });
+        }
+    }
+}
+export async function handleSessionDeleteAll(msg) {
+    const params = msg.params;
+    if (!params?.projectId) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INVALID_PARAMS,
+                message: "Missing required param: projectId",
+            });
+        }
+        return;
+    }
+    try {
+        const projectRoot = sessionQueries.getProjectWorkspaceDir(params.projectId);
+        const sessions = (await listSessions(10000, projectRoot))
+            .filter((session) => session.projectId === params.projectId);
+        let deletedCount = 0;
+        for (const session of sessions) {
+            await deleteSession(session.sessionId, projectRoot);
+            deletedCount++;
+        }
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, { ok: true, deletedCount });
+        }
+    }
+    catch (err) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INTERNAL_ERROR,
+                message: `Failed to delete all sessions: ${errorMessage(err)}`,
+            });
+        }
+    }
+}
+export async function handleSessionArchive(msg) {
+    const params = msg.params;
+    if (!params?.sessionId) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INVALID_PARAMS,
+                message: "Missing required param: sessionId",
+            });
+        }
+        return;
+    }
+    try {
+        const workspaceDir = resolveSessionWorkspaceDir(this, params.sessionId, params.projectId);
+        await updateSessionMetadata(params.sessionId, {
+            archivedAt: new Date().toISOString(),
+        }, workspaceDir);
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, { ok: true });
+        }
+    }
+    catch (err) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INTERNAL_ERROR,
+                message: `Failed to archive session: ${errorMessage(err)}`,
+            });
+        }
+    }
+}
+export async function handleSessionResume(msg) {
+    const params = msg.params;
+    const targetSessionId = params?.sessionId;
+    if (!targetSessionId) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INVALID_PARAMS,
+                message: "sessionId is required",
+            });
+        }
+        return;
+    }
+    try {
+        const workspaceDir = resolveSessionWorkspaceDir(this, targetSessionId, params?.projectId);
+        const session = await loadSessionForResume(targetSessionId, workspaceDir);
+        if (!session) {
+            if (msg.id !== undefined) {
+                this.sendResponse(msg.id, undefined, {
+                    code: AGENT_RPC_ERROR_CODES.INVALID_PARAMS,
+                    message: `Session not found: ${targetSessionId}`,
+                });
+            }
+            return;
+        }
+        // Cache resumed history so subsequent turns include prior context
+        if (session.messages && session.messages.length > 0) {
+            this.sessionHistory.saveResumedSession(targetSessionId, session.messages);
+        }
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, {
+                metadata: session.metadata,
+                messages: session.messages,
+            });
+        }
+    }
+    catch (err) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INTERNAL_ERROR,
+                message: `Failed to resume session: ${errorMessage(err)}`,
+            });
+        }
+    }
+}
+export function handleSessionGetInfo(msg) {
+    const sessionId = this.currentSessionId || "default";
+    const snap = this.sessionState?.createSnapshot();
+    let sessionDir;
+    // Use getActiveProjectRoot() (set during turn setup) - no filesystem scanning
+    const activeRoot = this.getActiveProjectRoot();
+    if (activeRoot) {
+        sessionDir = path.join(getProjectSessionsRoot(activeRoot), sessionId);
+    }
+    const result = {
+        sessionId,
+        model: this.currentModel || undefined,
+        cwd: process.cwd(),
+        paths: {
+            sessionDir,
+            agentHome: getUserAgentHome(),
+            settings: getUserSettingsPath(),
+        },
+        usage: snap
+            ? {
+                turnCount: snap.turnCount,
+                inputTokens: snap.totalInputTokens,
+                outputTokens: snap.totalOutputTokens,
+            }
+            : undefined,
+    };
+    if (msg.id !== undefined) {
+        this.sendResponse(msg.id, result);
+    }
+}
+// Project switching
+export function handleSessionSwitchProject(msg) {
+    const params = msg.params;
+    // Resolve project: by ID or by name
+    let project = null;
+    if (params?.projectId) {
+        project = projectStore.getProjectById(params.projectId);
+    }
+    else if (params?.projectName) {
+        const allProjects = projectStore.listProjects();
+        const nameLower = params.projectName.toLowerCase();
+        project = allProjects.find(p => p.name.toLowerCase() === nameLower) ?? null;
+        if (!project) {
+            project = allProjects.find(p => p.name.toLowerCase().includes(nameLower)) ?? null;
+        }
+        if (!project) {
+            const candidates = allProjects.map(p => p.name).slice(0, 10);
+            if (msg.id !== undefined) {
+                this.sendResponse(msg.id, undefined, {
+                    code: AGENT_RPC_ERROR_CODES.INTERNAL_ERROR,
+                    message: `No project matching "${params.projectName}". Available: ${candidates.join(", ") || "(none)"}`,
+                });
+            }
+            return;
+        }
+    }
+    else {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INVALID_PARAMS,
+                message: "Missing required param: projectId or projectName",
+            });
+        }
+        return;
+    }
+    if (!project || project.status !== "active") {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INTERNAL_ERROR,
+                message: `Project not found or archived: ${params.projectId ?? params.projectName}`,
+            });
+        }
+        return;
+    }
+    // Validate workspace dir exists
+    const dir = params.workspaceDir ?? project.workspaceDir;
+    if (!fs.existsSync(dir)) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INTERNAL_ERROR,
+                message: `Workspace directory does not exist: ${dir}`,
+            });
+        }
+        return;
+    }
+    const switched = projectStore.switchProject(project.id);
+    if (!switched) {
+        if (msg.id !== undefined) {
+            this.sendResponse(msg.id, undefined, {
+                code: AGENT_RPC_ERROR_CODES.INTERNAL_ERROR,
+                message: "Switch failed",
+            });
+        }
+        return;
+    }
+    // Update active workdir so instructions/plans resolve to the new project
+    this.setActiveWorkdir(switched.workspaceDir);
+    this.sendNotification("project.switched", {
+        id: switched.id,
+        name: switched.name,
+        workspaceDir: switched.workspaceDir,
+    });
+    if (msg.id !== undefined) {
+        this.sendResponse(msg.id, { ok: true, project: switched });
+    }
+}
+export function handleSessionGetState(msg) {
+    const activeProject = projectStore.getActiveProject();
+    const projects = projectStore.listProjects();
+    if (msg.id !== undefined) {
+        this.sendResponse(msg.id, {
+            sessionId: this.currentSessionId,
+            activeProject,
+            projects,
+        });
+    }
+}
+/**
+ * `session.focus` - Desktop UI reports which session is currently focused.
+ * Agent switches active project/cwd to the session's owning project.
+ */
+export async function handleSessionFocus(msg) {
+    const params = msg.params;
+    const sessionId = params?.sessionId;
+    if (!sessionId) {
+        if (msg.id !== undefined)
+            this.sendResponse(msg.id, { ok: false });
+        return;
+    }
+    // Try to find the session's projectId and switch to it
+    const projects = projectStore.listProjects();
+    for (const project of projects) {
+        try {
+            const workspaceDir = sessionQueries.getProjectWorkspaceDir(project.id);
+            const meta = await getSessionMetadata(sessionId, workspaceDir);
+            if (meta && meta.projectId === project.id) {
+                // Switch active project in store (not just workdir)
+                projectStore.switchProject(project.id);
+                this.setActiveWorkdir(workspaceDir);
+                this.log(`[session.focus] switched to project ${project.id} for session ${sessionId}`);
+                if (msg.id !== undefined)
+                    this.sendResponse(msg.id, { ok: true, projectId: project.id });
+                return;
+            }
+        }
+        catch { /* project dir inaccessible - skip */ }
+    }
+    // Fallback: if projectName was given, try to match by name
+    if (params?.projectName) {
+        const byName = projects.find(p => p.name === params.projectName);
+        if (byName) {
+            const workspaceDir = sessionQueries.getProjectWorkspaceDir(byName.id);
+            if (this.getActiveProjectRoot() !== workspaceDir) {
+                this.setActiveWorkdir(workspaceDir);
+                this.log(`[session.focus] switched to project ${byName.id} by name "${params.projectName}"`);
+            }
+            if (msg.id !== undefined)
+                this.sendResponse(msg.id, { ok: true, projectId: byName.id });
+            return;
+        }
+    }
+    if (msg.id !== undefined)
+        this.sendResponse(msg.id, { ok: false });
+}
+/**
+ * `session.moveToProject` - Move a session from one project to another.
+ * Physically copies session files, updates metadata.projectId, then removes the source.
+ * Emits session:updated notification.
+ */
+export async function handleSessionMoveToProject(msg) {
+    const params = msg.params;
+    const { sessionId, fromProjectId, toProjectId } = params ?? {};
+    if (!sessionId || !fromProjectId || !toProjectId) {
+        if (msg.id !== undefined) {
+            this.sendError(msg.id, AGENT_RPC_ERROR_CODES.INVALID_PARAMS, "sessionId, fromProjectId, and toProjectId are required");
+        }
+        return;
+    }
+    if (fromProjectId === toProjectId) {
+        if (msg.id !== undefined)
+            this.sendResponse(msg.id, { ok: true });
+        return;
+    }
+    // Validate projects exist
+    const fromProject = projectStore.getProjectById(fromProjectId);
+    const toProject = projectStore.getProjectById(toProjectId);
+    if (!fromProject || !toProject) {
+        if (msg.id !== undefined) {
+            this.sendError(msg.id, AGENT_RPC_ERROR_CODES.INVALID_PARAMS, "Source or target project not found");
+        }
+        return;
+    }
+    const fromDir = path.join(sessionQueries.getProjectWorkspaceDir(fromProjectId), ".qlogicagent", "sessions", sessionId);
+    const toDir = path.join(sessionQueries.getProjectWorkspaceDir(toProjectId), ".qlogicagent", "sessions", sessionId);
+    if (!fs.existsSync(fromDir)) {
+        if (msg.id !== undefined) {
+            this.sendError(msg.id, AGENT_RPC_ERROR_CODES.INVALID_PARAMS, `Session ${sessionId} not found in project ${fromProjectId}`);
+        }
+        return;
+    }
+    try {
+        // 1. Copy to new location
+        fs.mkdirSync(path.dirname(toDir), { recursive: true });
+        fs.cpSync(fromDir, toDir, { recursive: true });
+        // 2. Update metadata.json with new projectId
+        const metaPath = path.join(toDir, "metadata.json");
+        if (fs.existsSync(metaPath)) {
+            const meta = JSON.parse(fs.readFileSync(metaPath, "utf-8"));
+            meta.projectId = toProjectId;
+            fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+        }
+        // 3. Remove source
+        fs.rmSync(fromDir, { recursive: true, force: true });
+        // 4. Notify
+        this.sendNotification("session-update", {
+            sessionId,
+            projectId: toProjectId,
+        });
+        this.log(`[session.moveToProject] moved ${sessionId}: ${fromProjectId} -> ${toProjectId}`);
+        if (msg.id !== undefined)
+            this.sendResponse(msg.id, { ok: true, projectId: toProjectId });
+    }
+    catch (err) {
+        const message = errorMessage(err);
+        this.log(`[session.moveToProject] error: ${message}`);
+        if (msg.id !== undefined) {
+            this.sendError(msg.id, AGENT_RPC_ERROR_CODES.INTERNAL_ERROR, `Move failed: ${message}`);
+        }
+    }
+}