@xalia/agent 0.6.1 → 0.6.3

package/src/chat/server/openSession.ts

@@ -1,3 +1,4 @@
+import OpenAI from "openai";
 import { strict as assert } from "assert";
 import { Tool } from "@modelcontextprotocol/sdk/types.js";
 
@@ -6,25 +7,19 @@ import {
   Configuration,
   getLogger,
   McpServerSettings,
-  prefsGetAutoApprove,
-  prefsSetAutoApprove,
   SavedAgentProfile,
 } from "@xalia/xmcp/sdk";
 
+import { Agent, createUserMessage } from "../../agent/agent";
 import {
-  Agent,
   ChatCompletionAssistantMessageParam,
   ChatCompletionMessageToolCall,
   ChatCompletionToolMessageParam,
-  createUserMessage,
-} from "../../agent/agent";
+} from "../../agent/llm";
 import { SkillManager } from "../../agent/sudoMcpServerManager";
 import { McpServerInfo } from "../../agent/mcpServerManager";
 import { IAgentEventHandler } from "../../agent/iAgentEventHandler";
-import {
-  createAgentWithoutSkills,
-  DEFAULT_LLM_MODEL,
-} from "../../agent/agentUtils";
+import { createAgentWithoutSkills } from "../../agent/agentUtils";
 import { IPlatform } from "../../agent/iplatform";
 
 import type {
@@ -37,15 +32,18 @@ import type {
   ServerModelUpdated,
   ServerUserMessage,
   ClientUserMessage,
-  ServerToolAutoApprovalSet,
   ClientSessionMessage,
   ServerSessionError,
   ServerUserAdded,
   ServerUserRemoved,
   ServerSessionInfo,
-  ServerSessionUpdate,
   ClientSetWorkspace,
+  ClientToServer,
+  ServerSessionFileContent,
   ClientSetMcpServerConfig,
+  ClientShareSession,
+  ClientSessionMessageBase,
+  ServerAgentPaused,
 } from "../protocol/messages";
 import { AsyncQueue } from "../utils/asyncQueue";
 import { MultiAsyncQueue } from "../utils/multiAsyncQueue";
@@ -57,13 +55,17 @@ import {
   TeamParticipant,
   SessionCreateData,
   UserMessageData,
+  SessionDescriptor,
 } from "../data/dataModels";
 import {
   Database,
   createSessionParticipantMap,
   UserData,
 } from "../data/database";
-import { ApprovalManager } from "../utils/approvalManager";
+import {
+  DbAgentPreferencesWriter,
+  ToolApprovalManager,
+} from "../utils/approvalManager";
 import { ChatErrorMessage, ChatFatalError } from "../protocol/errors";
 import { addDefaultChatTools } from "./tools";
 import { ChatContextManager, ICheckpointWriter } from "./chatContextManager";
@@ -71,17 +73,33 @@ import {
   llmUserMessageToUserMessageData,
   MESSAGE_INDEX_START_VALUE,
 } from "./conversation";
-import { ChatSessionFileManager } from "./sessionFileManager";
+import {
+  ChatSessionFileManager,
+  ISessionFileManager,
+  ISessionFileManagerEventHandler,
+} from "./sessionFileManager";
 import { IUserConnectionManager } from "./connectionManager";
 import { getErrorString } from "./errorUtils";
 import { NODE_PLATFORM } from "../../tool/nodePlatform";
 import { DbMcpServerConfigs } from "../data/dbMcpServerConfigs";
+import { SessionFileEntry } from "../data/dbSessionFileModels";
+import { ApiKeyManager } from "../data/apiKeyManager";
+import { DbSessionMessages } from "../data/dbSessionMessages";
+import { ISessionMessageSender } from "./openSessionMessageSender";
+
+/**
+ * The model to use when the AgentProfile does not specify one.
+ */
+const DEFAULT_CHAT_LLM_MODEL =
+  process.env["DEFAULT_LLM_MODEL"] || "anthropic/claude-sonnet-4.5";
 
 /**
  * Num messages to load at conversation startup.
  */
 export const DEFAULT_NUM_MESSGAES = 500;
 
+export const GUEST_TOKEN_PREFIX = "guest";
+
 const logger = getLogger();
 
 type QueuedClientMessage<
@@ -109,6 +127,170 @@ class DBCheckpointWriter implements ICheckpointWriter {
   }
 }
 
+export class ChatSessionMessageSender
+  implements ISessionMessageSender<ServerToClient>
+{
+  constructor(
+    public readonly connectionManager: IUserConnectionManager<ServerToClient>,
+    public readonly sessionParticipants: SessionParticipantMap
+  ) {}
+
+  broadcast(msg: ServerToClient): void {
+    const users: Set<string> = new Set(this.sessionParticipants.keys());
+    this.connectionManager.sendToUsers(users, msg);
+  }
+
+  sendTo(userUUID: string, msg: ServerToClient): void {
+    this.connectionManager.sendToUsers(new Set([userUUID]), msg);
+  }
+}
+
+class ChatSessionPlatform {
+  constructor(
+    private sender: ISessionMessageSender<ServerToClient>,
+    private sessionUUID: string,
+    private ownerUUID: string
+  ) {}
+
+  // IPlatform.openUrl
+  openUrl(url: string, authResultP: Promise<boolean>, display_name: string) {
+    // These requests are always passed to the original owner, since it is
+    // their settings that will be used for all MCP servers.
+    this.sender.broadcast({
+      type: "authentication_started",
+      session_id: this.sessionUUID,
+      url,
+    });
+    this.sender.sendTo(this.ownerUUID, {
+      type: "authenticate",
+      session_id: this.sessionUUID,
+      url,
+      display_name,
+    });
+
+    // TODO: auth timeout
+    // Don't stall this function waiting for authentication
+    void authResultP.then((result) => {
+      this.sender.broadcast({
+        type: "authentication_finished",
+        session_id: this.sessionUUID,
+        url,
+        result,
+      });
+    });
+  }
+
+  // IPlatform.load
+  load(filename: string): Promise<string> {
+    if (process.env.DEVELOPMENT === "1") {
+      return NODE_PLATFORM.load(filename);
+    }
+    throw new ChatErrorMessage("Platform.load not implemented");
+  }
+
+  // IPlatform.renderHTML
+  renderHTML(html: string): Promise<void> {
+    return new Promise<void>((r) => {
+      this.sender.broadcast({
+        type: "render_html",
+        html,
+        session_id: this.sessionUUID,
+      });
+      r();
+    });
+  }
+}
+
+export class ChatSessionAgentEventHandler implements IAgentEventHandler {
+  constructor(
+    private readonly sessionUUID: string,
+    private readonly sender: ISessionMessageSender<ServerToClient>,
+    private readonly approvalManager: ToolApprovalManager,
+    private readonly contextManager: ChatContextManager
+  ) {}
+
+  onCompletion(result: ChatCompletionAssistantMessageParam): void {
+    logger.debug(`[OpenSession.onCompletion] : ${JSON.stringify(result)}`);
+    // Nothing to broadcast. Caller will receive this via onAgentMessage.
+    this.contextManager.processAgentResponse(result);
+  }
+
+  onImage(image: OpenAI.Chat.Completions.ChatCompletionContentPartImage): void {
+    logger.debug(`[OpenSession.onImage] : ${image.image_url.url}`);
+    throw new Error("[OpenSession.onImage] unimplemented");
+  }
+
+  onToolCallResult(result: ChatCompletionToolMessageParam): void {
+    logger.debug(`[onToolCallResult] : ${JSON.stringify(result)}`);
+    const toolCallMessage = this.contextManager.processToolCallResult(result);
+    this.sender.broadcast(toolCallMessage);
+  }
+
+  async onToolCall(
+    toolCall: ChatCompletionMessageToolCall,
+    agentTool: boolean
+  ): Promise<boolean> {
+    if (agentTool) {
+      // "Agent" tools are considered internal to the agent, and are always
+      // permitted.  Inform all clients and immediately approve.
+      this.sender.broadcast({
+        type: "tool_call",
+        tool_call: toolCall,
+        session_id: this.sessionUUID,
+      });
+      return true;
+    }
+
+    // TODO: Need a proper mapping to/from MCP calls to tool names
+
+    const [serverName, tool] = toolCall.function.name.split("__");
+    const { approved, requested } = await this.approvalManager.getApproval(
+      serverName,
+      tool,
+      toolCall
+    );
+
+    // For now, the frontend uses the tool_call data in the
+    // "approve_tool_call" request to display the tool call data.  If approval
+    // was requested in this way, don't send the "tool_call" message as well.
+
+    if (approved && !requested) {
+      this.sender.broadcast({
+        type: "tool_call",
+        tool_call: toolCall,
+        session_id: this.sessionUUID,
+      });
+    }
+
+    return approved;
+  }
+
+  onAgentMessage(msg: string, end: boolean): Promise<void> {
+    logger.debug(
+      `[OpenSession.onAgentMessage] msg: ${msg}, end: ${String(end)}`
+    );
+
+    // Inform the contextManager and broadcast the ServerAgentMessageChunk
+    const agentMsgChunk = this.contextManager.processAgentMessage(msg, end);
+    this.sender.broadcast(agentMsgChunk);
+    return Promise.resolve();
+  }
+
+  onReasoning(reasoning: string): Promise<void> {
+    return new Promise<void>((r) => {
+      logger.debug(`[OpenSession.onReasoning]${reasoning}`);
+      if (reasoning.length > 0) {
+        this.sender.broadcast({
+          type: "agent_reasoning_chunk",
+          reasoning,
+          session_id: this.sessionUUID,
+        });
+      }
+      r();
+    });
+  }
+}
+
 /**
  * Describes a Session (conversation) with connected participants.
  *
@@ -119,7 +301,7 @@ class DBCheckpointWriter implements ICheckpointWriter {
  * be seen until user messages had been fully processed, which could block
  * tool approvals and other interactions).
  */
-export class OpenSession implements IAgentEventHandler, IPlatform {
+export class OpenSession implements ISessionFileManagerEventHandler {
   private readonly db: Database;
   private /* readonly */ agent: Agent;
   private readonly sessionUUID: string;
@@ -129,15 +311,18 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
   private readonly sessionParticipants: SessionParticipantMap;
   private readonly agentProfilePreferences: AgentPreferences;
   private /* readonly */ skillManager: SkillManager;
-  private readonly connectionManager: IUserConnectionManager<ServerToClient>;
+  private readonly sender: ChatSessionMessageSender;
   private readonly messageQueue: AsyncQueue<QueuedClientMessage>;
   private readonly userMessageQueue: MultiAsyncQueue<ServerUserMessage>;
   private readonly contextManager: ChatContextManager;
-  private readonly approvalManager: ApprovalManager;
+  private readonly approvalManager: ToolApprovalManager;
   private readonly savedAgentProfile: SavedAgentProfile;
+  private readonly sessionFileManager: ISessionFileManager;
   private isPersisted: boolean;
+  private accessToken: string | undefined;
   private sessionTitle: string;
   private sessionUpdatedAt: string;
+  private agentPaused: boolean;
 
   private constructor(
     db: Database,
@@ -149,8 +334,9 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     agentProfilePreferences: AgentPreferences,
     skillManager: SkillManager,
     contextManager: ChatContextManager,
-    connectionManager: IUserConnectionManager<ServerToClient>,
-    approvalManager: ApprovalManager = new ApprovalManager()
+    sender: ChatSessionMessageSender,
+    approvalManager: ToolApprovalManager,
+    fileManager: ISessionFileManager
   ) {
     this.db = db;
     this.agent = agent;
@@ -158,10 +344,11 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     this.teamUUID = sessionData.team_uuid;
     this.userUUID = sessionData.user_uuid;
     this.agentProfileUUID = sessionData.agent_profile_uuid;
+    this.accessToken = sessionData.access_token;
     this.sessionParticipants = sessionParticipants;
     this.agentProfilePreferences = agentProfilePreferences;
     this.skillManager = skillManager;
-    this.connectionManager = connectionManager;
+    this.sender = sender;
     this.messageQueue = new AsyncQueue<QueuedClientMessage>((m) =>
       this.processMessage(m)
     );
@@ -172,13 +359,18 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     this.contextManager = contextManager;
     this.approvalManager = approvalManager;
     this.savedAgentProfile = savedAgentProfile;
+    this.sessionFileManager = fileManager;
     this.isPersisted = isPersisted;
     this.sessionTitle = sessionData.title;
     this.sessionUpdatedAt = sessionData.updated_at;
+    this.agentPaused = sessionData.agent_paused;
+
+    fileManager.addEventHandler(this);
   }
 
   private static async init(
     db: Database,
+    isPersisted: boolean,
     sessionData: SessionData,
     savedAgentProfile: SavedAgentProfile,
     sessionMessages: SessionMessage[],
@@ -191,61 +383,54 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     connectionManager: IUserConnectionManager<ServerToClient>
   ): Promise<OpenSession> {
     const sessionId = sessionData.session_uuid;
-    const fileManager = new ChatSessionFileManager(sessionId, db);
-    const contextManager = new ChatContextManager(
+
+    const fileManager = await ChatSessionFileManager.init(db, sessionId);
+    const sender = new ChatSessionMessageSender(
+      connectionManager,
+      sessionParticipants
+    );
+    const platform = new ChatSessionPlatform(sender, sessionId, ownerData.uuid);
+    const toolApprovalManager = new ToolApprovalManager(
+      sessionData.session_uuid,
+      savedAgentProfile.uuid,
+      savedAgentProfile.preferences,
+      sender,
+      new DbAgentPreferencesWriter(db)
+    );
+    const { agent, skillManager, contextManager } = await createContextAndAgent(
+      sessionId,
       savedAgentProfile.profile.system_prompt,
+      savedAgentProfile.profile.model || DEFAULT_CHAT_LLM_MODEL,
       sessionMessages,
-      sessionId,
-      ownerData.uuid,
+      sessionData.workspace,
       sessionCheckpoint,
-      llmUrl,
-      savedAgentProfile.profile.model || DEFAULT_LLM_MODEL,
+      ownerData,
       ownerApiKey,
-      new DBCheckpointWriter(db, sessionId),
-      fileManager
+      llmUrl,
+      xmcpUrl,
+      fileManager,
+      sender,
+      platform,
+      toolApprovalManager
     );
-    if (sessionData.workspace) {
-      const ws = sessionData.workspace;
-      contextManager.setWorkspace(createUserMessage(ws.message, ws.imageB64));
-    }
 
     const openSession = new OpenSession(
       db,
-      {} as Agent, // Placeholder - will be replaced after agent creation
+      agent,
       sessionData,
       savedAgentProfile,
-      false /* isPersisted */,
+      isPersisted,
       sessionParticipants,
       savedAgentProfile.preferences,
-      {} as SkillManager, // Placeholder - will be replaced after agent creation
-      contextManager,
-      connectionManager
-    );
-
-    // Initialize an empty agent (to ensure there are no callbacks before
-    // the OpenSession and client are fully set up).
-
-    const xmcpConfig = Configuration.new(ownerApiKey, xmcpUrl, false);
-    const [agent, skillManager] = await createAgentWithoutSkills(
-      llmUrl,
-      savedAgentProfile.profile,
-      openSession,
-      openSession,
+      skillManager,
       contextManager,
-      ownerApiKey,
-      xmcpConfig,
-      undefined,
-      true
+      sender,
+      toolApprovalManager,
+      fileManager
     );
-    await addDefaultChatTools(agent, ownerData.timezone, openSession);
 
-    // Update OpenSession with real agent and skillManager
-    openSession.agent = agent;
-    openSession.skillManager = skillManager;
+    // Note, MCP servers have not been enabled yet
 
-    await openSession.restoreMcpSettings(
-      savedAgentProfile.profile.mcp_settings
-    );
     return openSession;
   }
 
@@ -270,15 +455,22 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     }
 
     const sessionParticipants = new Map<string, TeamParticipant>();
-    sessionParticipants.set(sessionData.user_uuid, {
-      user_uuid: sessionData.user_uuid,
-      nickname: ownerData.nickname || "",
-      email: ownerData.email,
-      role: "owner",
-    });
+    if (sessionData.participants && sessionData.participants.length > 0) {
+      sessionData.participants.forEach((p) => {
+        sessionParticipants.set(p.user_uuid, p);
+      });
+    } else {
+      sessionParticipants.set(sessionData.user_uuid, {
+        user_uuid: sessionData.user_uuid,
+        nickname: ownerData.nickname || "",
+        email: ownerData.email,
+        role: "owner",
+      });
+    }
 
     return OpenSession.init(
       db,
+      false /* isPersisted */,
       sessionData,
       savedAgentProfile,
       sessionMessages,
@@ -311,6 +503,7 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     } = await loadSessionData(db, sessionId);
     return OpenSession.init(
       db,
+      true /* isPersisted */,
       sessionData,
       savedAgentProfile,
       sessionMessages,
@@ -328,22 +521,66 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     logger.info(`[OpenSession.onEmpty] session ${this.sessionUUID}`);
   }
 
+  getDescriptor(): SessionDescriptor {
+    assert(
+      typeof this.accessToken === "string" ||
+        typeof this.accessToken === "undefined"
+    );
+    return {
+      session_uuid: this.sessionUUID,
+      title: this.sessionTitle,
+      agent_profile_uuid: this.agentProfileUUID,
+      user_uuid: this.userUUID,
+      team_uuid: this.teamUUID,
+      access_token: this.accessToken,
+      updated_at: this.sessionUpdatedAt,
+      agent_paused: this.agentPaused,
+    };
+  }
+
   getParticipants(): SessionParticipantMap {
     return this.sessionParticipants;
   }
 
-  sendSessionData(connectionId: string, clientMessageId: string): void {
+  async sendSessionData(
+    connectionId: string,
+    clientMessageId: string,
+    restoreMcpState: boolean
+  ): Promise<void> {
     logger.info(
       `[SessionRegistry] sending session data for session ${this.sessionUUID}`
     );
 
     const sessionInfo = this.serverSessionInfo(clientMessageId);
-    this.connectionManager.sendToConnection(connectionId, sessionInfo);
+    const connMgr = this.sender.connectionManager;
+    connMgr.sendToConnection(connectionId, sessionInfo);
+
+    // This could be cleaner.  If the session has just been created, we must
+    // restore the mcp servers.  However, we cannot do that until the client
+    // has initialized itself (in case we need auth messages), hence it must
+    // happen at this stage, BEFORE we call sendMcpSettings below.
+
+    if (restoreMcpState) {
+      await this.restoreMcpSettings(
+        this.savedAgentProfile.profile.mcp_settings
+      );
+    }
+
+    // send session file info
+    const fileDescriptors = this.sessionFileManager.listFiles();
+    fileDescriptors.forEach((descriptor) => {
+      connMgr.sendToConnection(connectionId, {
+        type: "session_file_changed",
+        session_id: this.sessionUUID,
+        descriptor,
+        new_file: false,
+      });
+    });
 
     // send conversation history
     const conversationMessages = this.contextManager.getConversationMessages();
     conversationMessages.forEach((message) => {
-      this.connectionManager.sendToConnection(connectionId, message);
+      connMgr.sendToConnection(connectionId, message);
     });
 
     // add MCP settings
@@ -351,12 +588,12 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
 
     // add system prompt and model
     const agentProfile = this.agent.getAgentProfile();
-    this.connectionManager.sendToConnection(connectionId, {
+    connMgr.sendToConnection(connectionId, {
       type: "system_prompt_updated",
       system_prompt: agentProfile.system_prompt,
       session_id: this.sessionUUID,
     });
-    this.connectionManager.sendToConnection(connectionId, {
+    connMgr.sendToConnection(connectionId, {
       type: "model_updated",
       model: agentProfile.model || "",
       session_id: this.sessionUUID,
@@ -407,7 +644,7 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
           skillManager.enableTool(server_name, enabled_tool);
         }
       } catch (e) {
-        this.broadcast({
+        this.sender.broadcast({
           type: "session_error",
           message: `Error adding MCP server ${server_name}: ${String(e)}`,
           session_id: this.sessionUUID,
@@ -426,9 +663,9 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
   private handleError(err: unknown, from?: string): boolean {
     const sendError = (msg: ServerSessionError) => {
       if (from) {
-        this.sendTo(from, msg);
+        this.sender.sendTo(from, msg);
       } else {
-        this.broadcast(msg);
+        this.sender.broadcast(msg);
       }
     };
 
@@ -458,162 +695,29 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     return true;
   }
 
-  private broadcast(msg: ServerToClient): void {
-    const users: Set<string> = new Set(this.sessionParticipants.keys());
-    this.connectionManager.sendToUsers(users, msg);
-  }
-
-  sendTo(user_uuid: string, msg: ServerToClient): void {
-    this.connectionManager.sendToUsers(new Set([user_uuid]), msg);
-  }
-
-  // IPlatform.openUrl
-  openUrl(url: string, authResultP: Promise<boolean>, display_name: string) {
-    // These requests are always passed to the original owner, since it is
-    // their settings that will be used for all MCP servers.
-    this.broadcast({
-      type: "authentication_started",
-      session_id: this.sessionUUID,
-      url,
-    });
-    this.sendTo(this.userUUID, {
-      type: "authenticate",
+  // ISessionFileManagerEventHandler.onFileDeleted
+  onFileDeleted(name: string): void {
+    this.sender.broadcast({
+      type: "session_file_deleted",
       session_id: this.sessionUUID,
-      url,
-      display_name,
+      name,
     });
-
-    // TODO: auth timeout
-    // Don't stall this function waiting for authentication
-    void authResultP.then((result) => {
-      this.sendTo(this.userUUID, {
-        type: "authentication_finished",
-        session_id: this.sessionUUID,
-        url,
-        result,
-      });
-    });
-  }
-
-  // IPlatform.load
-  load(filename: string): Promise<string> {
-    if (process.env.DEVELOPMENT === "1") {
-      return NODE_PLATFORM.load(filename);
-    }
-    throw new ChatErrorMessage("Platform.load not implemented");
   }
 
-  // IPlatform.renderHTML
-  renderHTML(html: string): Promise<void> {
-    return new Promise<void>((r) => {
-      this.broadcast({
-        type: "render_html",
-        html,
-        session_id: this.sessionUUID,
-      });
-      r();
+  // ISessionFileManagerEventHandler.onFileChanged
+  onFileChanged(entry: SessionFileEntry, new_file: boolean): void {
+    this.sender.broadcast({
+      type: "session_file_changed",
+      session_id: this.sessionUUID,
+      descriptor: {
+        name: entry.name,
+        mime_type: entry.mime_type,
+        summary: entry.summary,
+      },
+      new_file,
     });
   }
 
-  // IAgentEventHandler.onCompletion
-  onCompletion(result: ChatCompletionAssistantMessageParam): void {
-    logger.debug(`[OpenSession.onCompletion] : ${JSON.stringify(result)}`);
-    // Nothing to broadcast. Caller will receive this via onAgentMessage.
-    this.contextManager.processAgentResponse(result);
-  }
-
-  // IAgentEventHandler.onToolCallResult
-  onToolCallResult(result: ChatCompletionToolMessageParam): void {
-    logger.debug(`[onToolCallResult] : ${JSON.stringify(result)}`);
-    const toolCallMessage = this.contextManager.processToolCallResult(result);
-    this.broadcast(toolCallMessage);
-  }
-
-  // IAgentEventHandler.onToolCall
-  async onToolCall(
-    toolCall: ChatCompletionMessageToolCall,
-    agentTool: boolean
-  ): Promise<boolean> {
-    if (agentTool) {
-      // "Agent" tools are considered internal to the agent, and are always
-      // permitted.  Inform all clients and immediately approve.
-      this.broadcast({
-        type: "tool_call",
-        tool_call: toolCall,
-        session_id: this.sessionUUID,
-      });
-      return true;
-    }
-
-    // TODO: Need a proper mapping to/from MCP calls to tool names
-
-    const [serverName, tool] = toolCall.function.name.split("__");
-    const autoApproved = prefsGetAutoApprove(
-      this.agentProfilePreferences,
-      serverName,
-      tool
-    );
-    if (!autoApproved) {
-      const { id, resultP } = this.approvalManager.startApproval(
-        toolCall.function.name
-      );
-      this.broadcast({
-        type: "approve_tool_call",
-        id,
-        tool_call: toolCall,
-        session_id: this.sessionUUID,
-      });
-
-      try {
-        logger.debug(`[OpenSession.onToolCall] awaiting approval ${id}`);
-        const { approved, auto_approve } = await resultP;
-        logger.debug(
-          `[OpenSession.onToolCall] approval ${id}: ${String(approved)}`
-        );
-        if (auto_approve) {
-          logger.debug(
-            "[OpenSession.onToolCall] auto_approve set. updated preferences"
-          );
-          const autoApprovalMsg = await this.onSetAutoApproval(
-            serverName,
-            tool,
-            true
-          );
-          if (autoApprovalMsg) {
-            this.broadcast(autoApprovalMsg);
-          }
-        }
-
-        return approved;
-      } catch (e) {
-        logger.debug(
-          `[OpenSession.onToolCall] error waiting for approval ${id}: ` +
-            String(e)
-        );
-        return false;
-      }
-    } else {
-      this.broadcast({
-        type: "tool_call",
-        tool_call: toolCall,
-        session_id: this.sessionUUID,
-      });
-      return true;
-    }
-  }
-
-  // IAgentEventHandler.onAgentMessage
-  // eslint-disable-next-line @typescript-eslint/require-await
-  async onAgentMessage(msg: string, end: boolean): Promise<void> {
-    logger.debug(
-      `[OpenSession.onAgentMessage] msg: ${msg}, end: ${String(end)}`
-    );
-
-    // Inform the contextManager and broadcast the ServerAgentMessageChunk
-    const agentMsgChunk = this.contextManager.processAgentMessage(msg, end);
-    this.broadcast(agentMsgChunk);
-  }
-
   /**
    * Handle incoming session-related message from client.
    * These messages include tool calls, MCP changes, etc.
@@ -630,7 +734,7 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
       logger.warn(
         `User ${from} not in session ${this.sessionUUID} - ignoring message`
       );
-      this.sendTo(from, {
+      this.sender.sendTo(from, {
         type: "session_error",
         message: "You are not a participant in this session",
         session_id: this.sessionUUID,
@@ -641,7 +745,7 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
 
     // Enqueue message for processing
     if (!this.messageQueue.tryEnqueue({ msg: message, from })) {
-      this.sendTo(
+      this.sender.sendTo(
         from,
         this.addSessionContext({
           type: "session_error",
@@ -662,7 +766,7 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
       const mcpServer = this.skillManager.getMcpServer(server_name);
       const tools = mcpServer.getTools();
       const enabled_tools = Array.from(mcpServer.getEnabledTools().keys());
-      this.connectionManager.sendToConnection(connectionId, {
+      this.sender.connectionManager.sendToConnection(connectionId, {
         type: "mcp_server_added",
         server_name,
         tools,
@@ -693,70 +797,76 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
         undefined;
       switch (msg.type) {
         case "msg":
-          broadcastMsg = this.onUserMessage(msg, queuedMessage.from);
+          broadcastMsg = await this.handleUserMessage(msg, queuedMessage.from);
           break;
         case "add_mcp_server":
-          broadcastMsg = await this.onAddMcpServer(
+          broadcastMsg = await this.handleAddMcpServer(
             msg.server_name,
             msg.enable_all
           );
           break;
         case "remove_mcp_server":
-          broadcastMsg = await this.onRemoveMcpServer(msg.server_name);
+          broadcastMsg = await this.handleRemoveMcpServer(msg.server_name);
           break;
         case "enable_mcp_server_tool":
-          broadcastMsg = await this.onEnableMcpServerTool(
+          broadcastMsg = await this.handleEnableMcpServerTool(
             msg.server_name,
             msg.tool
           );
           break;
         case "disable_mcp_server_tool":
-          broadcastMsg = await this.onDisableMcpServerTool(
+          broadcastMsg = await this.handleDisableMcpServerTool(
             msg.server_name,
             msg.tool
           );
           break;
         case "enable_all_mcp_server_tools":
-          broadcastMsg = await this.onEnableAllMcpServerTools(msg.server_name);
+          broadcastMsg = await this.handleEnableAllMcpServerTools(
+            msg.server_name
+          );
           break;
         case "disable_all_mcp_server_tools":
-          broadcastMsg = await this.onDisableAllMcpServerTools(msg.server_name);
+          broadcastMsg = await this.handleDisableAllMcpServerTools(
+            msg.server_name
+          );
           break;
         case "tool_call_approval_result":
-          if (
-            this.approvalManager.approvalResult(
-              msg.id,
-              msg.result,
-              msg.auto_approve
-            )
-          ) {
-            broadcastMsg = {
-              type: "tool_call_approval_result",
-              id: msg.id,
-              result: msg.result,
-              session_id: this.sessionUUID,
-            };
-          }
+          this.approvalManager.onApprovalResult(msg);
+          break;
+        case "session_file_get_content":
+          void this.handleSessionFileGetContent(msg, queuedMessage.from);
+          break;
+        case "session_file_delete":
+          await this.handleSessionFileDelete(msg);
+          break;
+        case "session_file_put_content":
+          await this.handleSessionFilePutContent(msg);
           break;
         case "set_auto_approval":
-          broadcastMsg = await this.onSetAutoApproval(
+          broadcastMsg = await this.approvalManager.setAutoApprove(
             msg.server_name,
             msg.tool,
             msg.auto_approve
           );
           break;
         case "set_system_prompt":
-          broadcastMsg = await this.onSetSystemPrompt(msg.system_prompt);
+          broadcastMsg = await this.handleSetSystemPrompt(msg.system_prompt);
           break;
         case "set_model":
-          broadcastMsg = await this.onSetModel(msg.model);
+          broadcastMsg = await this.handleSetModel(msg.model);
+          break;
+        case "set_agent_paused":
+          broadcastMsg = await this.handleSetAgentPaused(msg.paused);
           break;
         case "set_workspace":
-          await this.onSetWorkspace(msg, queuedMessage.from);
+          await this.handleSetWorkspace(msg, queuedMessage.from);
           break;
         case "set_mcp_server_config":
           await this.handleSetMcpServerConfig(msg, queuedMessage.from);
           break;
+        case "share_session":
+          await this.handleShareSession(msg, queuedMessage.from);
+          break;
         default: {
           const exhaustive: never = msg; // Error => non-exhaustive switch-case.
           return exhaustive;
@@ -766,10 +876,10 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
       if (broadcastMsg) {
         if (broadcastMsg instanceof Array) {
           broadcastMsg.map((msg) => {
-            this.broadcast(msg);
+            this.sender.broadcast(msg);
           });
         } else {
-          this.broadcast(broadcastMsg);
+          this.sender.broadcast(broadcastMsg);
         }
       }
     } catch (err: unknown) {
@@ -779,7 +889,28 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     }
   }
 
-  private async onSetWorkspace(
+  private async handleShareSession(
+    msg: ClientShareSession & ClientSessionMessageBase,
+    from: string
+  ) {
+    if (!this.accessToken) {
+      const accessToken = ApiKeyManager.createApiKeyWithPayload(
+        GUEST_TOKEN_PREFIX,
+        this.sessionUUID
+      );
+      await this.db.sessionUpdateAccessToken(this.sessionUUID, accessToken);
+      this.accessToken = accessToken;
+    }
+
+    this.sender.sendTo(from, {
+      type: "session_shared",
+      access_token: this.accessToken,
+      client_message_id: msg.client_message_id,
+      session_id: this.sessionUUID,
+    });
+  }
+
+  private async handleSetWorkspace(
     msg: ClientSetWorkspace,
     sender: string
   ): Promise<void> {
@@ -799,18 +930,28 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     assert(this.isPersisted);
   }
 
-  private async processUserMessages(msgs: ServerUserMessage[]): Promise<void> {
-    if (msgs.length === 0) {
-      logger.debug("ignoring empty messages");
-      return;
-    }
+  /**
+   * `processUserMessage` logic when agent is paused.  Trigger the context,
+   * add the user messages and then extract the new DB messages.
+   */
+  private processUserMessagePaused(
+    msgs: ServerUserMessage[]
+  ): SessionMessage[] {
+    const { llmUserMessages } = this.contextManager.startAgentResponse(msgs);
+
+    // Just send the user LLM messages direct to the ContextManager, so they
+    // are available to the LLM once it is restarted.
 
-    // Begin an agent response using the accumulated user messages.
+    this.contextManager.addMessages(llmUserMessages);
+    return this.contextManager.endAgentResponse();
+  }
 
+  private async processUserMessagesActive(
+    msgs: ServerUserMessage[]
+  ): Promise<SessionMessage[]> {
     const { llmUserMessages, agentFirstChunk } =
       this.contextManager.startAgentResponse(msgs);
-    this.broadcast(agentFirstChunk);
-
+    this.sender.broadcast(agentFirstChunk);
     try {
       await this.agent.userMessagesRaw(llmUserMessages);
     } catch (e) {
@@ -821,22 +962,26 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
       // Errors during agent replies must be turned into messages.
 
       const errMsg = `error from LLM: ${String(e)}`;
-      await this.onAgentMessage(errMsg, true);
-      const err = this.contextManager.revertAgentResponse(errMsg);
-      this.broadcast(err);
-      return;
+      this.contextManager.revertAgentResponse(errMsg);
+      throw new Error(errMsg);
     }
+    return this.contextManager.endAgentResponse();
+  }
 
-    const newSessionMessages = this.contextManager.endAgentResponse();
+  private async processUserMessages(msgs: ServerUserMessage[]): Promise<void> {
+    try {
+      const newSessionMessages = this.agentPaused
+        ? this.processUserMessagePaused(msgs)
+        : await this.processUserMessagesActive(msgs);
 
-    logger.debug(
-      "[processUserMessages] newSessionMessages: " +
-        JSON.stringify(newSessionMessages)
-    );
+      logger.debug(
+        "[processUserMessages] newSessionMessages: " +
+          JSON.stringify(newSessionMessages)
+      );
 
-    try {
       // Append to in-memory conversation and write to the DB
-      await this.db.sessionMessagesAppend(this.sessionUUID, newSessionMessages);
+      const dbsm = this.db.createTypedClient(DbSessionMessages);
+      await dbsm.append(this.sessionUUID, newSessionMessages);
     } catch (e) {
       if (!this.handleError(e)) {
         throw e;
@@ -844,10 +989,10 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     }
   }
 
-  private onUserMessage(
+  private async handleUserMessage(
     msg: ClientUserMessage,
     from: string
-  ): ServerUserMessage | undefined {
+  ): Promise<ServerUserMessage | undefined> {
     // Return a ServerUserMessage for broadcast.  The actual message is places
     // on a queue to be dealt with in another loop.  This allows Agent
     // processing of user messages to depend on other messages.
@@ -857,13 +1002,23 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
 
     // Assign the user message_idx and attempt to enqueue.
 
-    const userMessage = this.contextManager.processUserMessage(msg, from);
-
+    const user = this.sessionParticipants.get(from);
+    if (!user) {
+      throw new Error(`unrecognized user ${from}`);
+    }
+    const userMessage = this.contextManager.processUserMessage(
+      msg,
+      from,
+      user.nickname
+    );
+    if (!userMessage) {
+      return;
+    }
     // Special case for the first message of the session
 
     if (userMessage.message_idx === MESSAGE_INDEX_START_VALUE) {
       // No need to wait for this to complete before broadcasting.
-      void this.onFirstMessage(userMessage);
+      await this.onFirstMessage(userMessage);
     }
 
     if (!this.userMessageQueue.tryEnqueue(userMessage)) {
@@ -874,7 +1029,7 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
 
       this.contextManager.unprocessUserMessage(userMessage);
 
-      this.sendTo(from, {
+      this.sender.sendTo(from, {
         type: "session_error",
         message: "failed to queue message.  try again later.",
         session_id: this.sessionUUID,
@@ -893,14 +1048,20 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
       title: this.sessionTitle,
       team_uuid: this.teamUUID,
       agent_profile_uuid: this.agentProfileUUID,
-      workspace: this.workspaceUserMessageData(),
       user_uuid: this.userUUID,
+      agent_paused: false,
     };
     logger.info(
       `[OpenSession.onFirstMessage] writing session ${this.sessionUUID}`
     );
 
     await this.db.sessionCreate(sessionCreateData);
+
+    const workspace = this.workspaceUserMessageData();
+    if (workspace) {
+      await this.db.sessionUpdateWorkspace(this.sessionUUID, workspace);
+    }
+
     this.isPersisted = true;
   }
 
@@ -919,17 +1080,42 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     }
     assert(this.isPersisted);
 
-    // Broadcast the SessionUpdated message
+    // Send session created notification
+    const sessionInfo = this.serverSessionInfo("");
+    
+    if (this.teamUUID) {
+      // Team session: notify all members about the new session
+      try {
+        const teamMembers = await this.db.teamGetMembers(this.teamUUID);
+        const teamMemberIds = new Set(teamMembers.map((m) => m.user_uuid));
 
-    const msg: ServerSessionUpdate = {
-      type: "session_update",
-      session_id: this.sessionUUID,
-      title: this.sessionTitle,
-    };
-    this.broadcast(msg);
+        this.sender.connectionManager.sendToUsers(teamMemberIds, sessionInfo);
+
+        logger.info(
+          `[OpenSession] notified ${String(teamMemberIds.size)} team members` +
+            ` about new session ${this.sessionUUID} in team ${this.teamUUID}`
+        );
+      } catch (error) {
+        logger.error(
+          "[OpenSession] Error notifying team members about session" +
+            `${this.sessionUUID}: ${String(error)}`
+        );
+      }
+    } else {
+      // If this is a user session, notify the session owner
+      this.sender.connectionManager.sendToUsers(
+        new Set([this.userUUID]),
+        sessionInfo
+      );
+      
+      logger.info(
+        `[OpenSession] notified session owner ${this.userUUID} about ` +
+        `new session ${this.sessionUUID}`
+      );
+    }
   }
 
-  private async onAddMcpServer(
+  private async handleAddMcpServer(
     serverName: string,
     enableAll: boolean
   ): Promise<ServerMcpServerAdded> {
@@ -967,7 +1153,7 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     };
   }
 
-  private async onRemoveMcpServer(
+  private async handleRemoveMcpServer(
     server_name: string
   ): Promise<ServerMcpServerRemoved> {
     logger.info(`[onRemoveMcpServer]: Removing server ${server_name}`);
@@ -986,7 +1172,7 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     };
   }
 
-  private async onEnableMcpServerTool(
+  private async handleEnableMcpServerTool(
     server_name: string,
     tool: string
   ): Promise<ServerMcpServerToolEnabled> {
@@ -1003,7 +1189,7 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     };
   }
 
-  private async onDisableMcpServerTool(
+  private async handleDisableMcpServerTool(
     server_name: string,
     tool: string
   ): Promise<ServerMcpServerToolDisabled> {
@@ -1020,7 +1206,7 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     };
   }
 
-  private async onEnableAllMcpServerTools(
+  private async handleEnableAllMcpServerTools(
     server_name: string
   ): Promise<ServerMcpServerToolEnabled[]> {
     // We reimplement the logic to enable any disabled tools so we can
@@ -1046,7 +1232,7 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     return msgs;
   }
 
-  private async onDisableAllMcpServerTools(
+  private async handleDisableAllMcpServerTools(
     server_name: string
   ): Promise<ServerMcpServerToolDisabled[]> {
     // We reimplement the logic to disable all enabled tools so we can
@@ -1070,7 +1256,7 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     return msgs;
   }
 
-  private async onSetSystemPrompt(
+  private async handleSetSystemPrompt(
     system_prompt: string
   ): Promise<ServerSystemPromptUpdated> {
     this.agent.setSystemPrompt(system_prompt);
@@ -1082,12 +1268,20 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     };
   }
 
-  private async onSetModel(model: string): Promise<ServerModelUpdated> {
+  private async handleSetModel(model: string): Promise<ServerModelUpdated> {
     this.agent.setModel(model);
     await this.updateAgentProfile();
     return { type: "model_updated", model, session_id: this.sessionUUID };
   }
 
+  private async handleSetAgentPaused(
+    paused: boolean
+  ): Promise<ServerAgentPaused> {
+    this.agentPaused = paused;
+    await this.db.sessionSetAgentPaused(this.sessionUUID, paused);
+    return { type: "agent_paused", session_id: this.sessionUUID, paused };
+  }
+
   private async handleSetMcpServerConfig(
     msg: ClientSetMcpServerConfig,
     from: string
@@ -1120,32 +1314,48 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
     // TODO: Do we want to braodcast an "mcp_server_config_updated" message?
   }
 
-  private async onSetAutoApproval(
-    serverName: string,
-    tool: string,
-    autoApprove: boolean
-  ): Promise<ServerToolAutoApprovalSet | undefined> {
-    if (
-      prefsSetAutoApprove(
-        this.agentProfilePreferences,
-        serverName,
-        tool,
-        autoApprove
-      )
-    ) {
-      await this.db.updateAgentProfilePreferences(
-        this.agentProfileUUID,
-        this.agentProfilePreferences
-      );
+  private async handleSessionFileGetContent(
+    msg: Extract<ClientToServer, { type: "session_file_get_content" }>,
+    from: string
+  ): Promise<void> {
+    const data_url = await this.sessionFileManager.getFileContent(msg.name);
+    const contentMsg: ServerSessionFileContent = {
+      type: "session_file_content",
+      session_id: this.sessionUUID,
+      client_message_id: msg.client_message_id,
+      name: msg.name,
+      data_url,
+    };
+    this.sender.sendTo(from, contentMsg);
+  }
 
-      return {
-        type: "tool_auto_approval_set",
-        server_name: serverName,
-        tool,
-        auto_approve: autoApprove,
-        session_id: this.sessionUUID,
-      };
+  private async handleSessionFileDelete(
+    msg: Extract<ClientToServer, { type: "session_file_delete" }>
+  ): Promise<void> {
+    await this.sessionFileManager.deleteFile(msg.name);
+    // Note, the SessionFileManager will call us back via
+    // `ISessionFileManagerEventHandler.onFileDeleted` if the deletion
+    // succeeds.  We broadcast in that callback.
+  }
+
+  private async handleSessionFilePutContent(
+    msg: Extract<ClientToServer, { type: "session_file_put_content" }>
+  ): Promise<void> {
+    // If the session hasn't been persisted, it must be written to the DB,
+    // (otherwise the sessionId in the SessionFiles entry will not be
+    // considered valid byt he DB).
+
+    if (!this.isPersisted) {
+      await this.createSessionInDB();
     }
+    await this.sessionFileManager.putFileContent(
+      msg.name,
+      msg.summary,
+      msg.data_url
+    );
+    // Note, the SessionFileManager will call us back via
+    // `ISessionFileManagerEventHandler.onFileChanged` if the deletion
+    // succeeds.  We broadcast in that callback.
   }
 
   private ensureMcpServer(serverName: string): McpServerInfo {
@@ -1175,19 +1385,19 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
    * This only updates the local participant map - actual membership
    * tracking is handled by SessionRegistry.
    */
-  addParticipant(userId: string, role: TeamParticipant): void {
-    this.sessionParticipants.set(userId, role);
+  addParticipant(userId: string, participant: TeamParticipant): void {
+    this.sessionParticipants.set(userId, participant);
     // Broadcast result to all session participants
     const broadcastMessage: ServerUserAdded = {
       type: "user_added",
       user_uuid: userId,
       role: "participant",
-      nickname: role.nickname,
-      email: role.email,
+      nickname: participant.nickname,
+      email: participant.email,
       session_id: this.sessionUUID,
     };
 
-    this.broadcast(broadcastMessage);
+    this.sender.broadcast(broadcastMessage);
   }
 
   /**
@@ -1204,7 +1414,7 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
       session_id: this.sessionUUID,
     };
 
-    this.broadcast(broadcastMessage);
+    this.sender.broadcast(broadcastMessage);
   }
 
   private getSessionParticipants(): TeamParticipant[] {
@@ -1239,6 +1449,7 @@ export class OpenSession implements IAgentEventHandler, IPlatform {
       client_message_id: clientMessageId,
       session_id: this.sessionUUID,
       team_uuid: this.teamUUID,
+      agent_paused: this.agentPaused,
     };
   }
 
@@ -1302,10 +1513,11 @@ async function loadSessionData(
   ownerApiKey: string;
   sessionParticipants: SessionParticipantMap;
 }> {
+  const dbsm = db.createTypedClient(DbSessionMessages);
   const [sessionData, sessionMessages, sessionParticipants, sessionCheckpoint] =
     await Promise.all([
-      db.sessionGetById(sessionId),
-      db.sessionMessagesGetConversation(sessionId, DEFAULT_NUM_MESSGAES, 0),
+      db.sessionGetDescriptorById(sessionId),
+      dbsm.getConversation(sessionId, DEFAULT_NUM_MESSGAES, 0),
       db.sessionGetParticipants(sessionId),
       db.sessionCheckpointGet(sessionId),
     ]);
@@ -1330,3 +1542,72 @@ async function loadSessionData(
     sessionParticipants: createSessionParticipantMap(sessionParticipants),
   };
 }
+
+async function createContextAndAgent(
+  sessionUUID: string,
+  systemPrompt: string,
+  model: string,
+  sessionMessages: SessionMessage[],
+  workspace: UserMessageData | undefined,
+  sessionCheckpoint: SessionCheckpoint | undefined,
+  ownerData: UserData,
+  ownerApiKey: string,
+  llmUrl: string,
+  xmcpUrl: string,
+  fileManager: ChatSessionFileManager,
+  sender: ISessionMessageSender<ServerToClient>,
+  platform: IPlatform,
+  approvalManager: ToolApprovalManager
+): Promise<{
+  agent: Agent;
+  skillManager: SkillManager;
+  contextManager: ChatContextManager;
+}> {
+  const contextManager = new ChatContextManager(
+    systemPrompt,
+    sessionMessages,
+    sessionUUID,
+    ownerData.uuid,
+    sessionCheckpoint,
+    llmUrl,
+    model,
+    ownerApiKey,
+    undefined as unknown as DBCheckpointWriter, // TODO
+    fileManager
+  );
+  if (workspace) {
+    contextManager.setWorkspace(
+      createUserMessage(workspace.message, workspace.imageB64)
+    );
+  }
+
+  const eventHandler = new ChatSessionAgentEventHandler(
+    sessionUUID,
+    sender,
+    approvalManager,
+    contextManager
+  );
+
+  const xmcpConfig = Configuration.new(ownerApiKey, xmcpUrl, false);
+  const [agent, skillManager] = await createAgentWithoutSkills(
+    llmUrl,
+    model,
+    eventHandler,
+    platform,
+    contextManager,
+    ownerApiKey,
+    xmcpConfig,
+    undefined,
+    true
+  );
+  await addDefaultChatTools(
+    agent,
+    ownerData.timezone,
+    platform,
+    fileManager,
+    llmUrl,
+    ownerApiKey
+  );
+
+  return { agent, skillManager, contextManager };
+}