Copilot Architecture

Relevant source files

• apps/sim/app/api/copilot/chat/route.ts
• apps/sim/app/api/copilot/chat/stream/route.ts
• apps/sim/app/api/copilot/chat/update-messages/route.ts
• apps/sim/app/api/copilot/chats/route.ts
• apps/sim/app/api/mothership/chat/route.ts
• apps/sim/app/api/mothership/chats/[chatId]/route.ts
• apps/sim/app/api/mothership/execute/route.ts
• apps/sim/app/api/v1/copilot/chat/route.ts
• apps/sim/app/api/workflows/[id]/execute/route.async.test.ts
• apps/sim/app/workspace/[workspaceId]/home/components/index.ts
• apps/sim/app/workspace/[workspaceId]/home/components/message-content/components/agent-group/agent-group.tsx
• apps/sim/app/workspace/[workspaceId]/home/components/message-content/message-content.tsx
• apps/sim/app/workspace/[workspaceId]/home/components/mothership-chat/mothership-chat.tsx
• apps/sim/app/workspace/[workspaceId]/home/components/queued-messages/index.ts
• apps/sim/app/workspace/[workspaceId]/home/components/queued-messages/queued-messages.tsx
• apps/sim/app/workspace/[workspaceId]/home/home.tsx
• apps/sim/app/workspace/[workspaceId]/home/hooks/index.ts
• apps/sim/app/workspace/[workspaceId]/home/hooks/use-chat.ts
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/diff-controls/diff-controls.tsx
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/copilot/components/user-input/constants.ts
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/panel.tsx
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-current-workflow.ts
• apps/sim/hooks/queries/tasks.ts
• apps/sim/lib/copilot/chat-payload.ts
• apps/sim/lib/copilot/chat-streaming.ts
• apps/sim/lib/copilot/orchestrator/index.ts
• apps/sim/lib/copilot/orchestrator/sse/handlers/handlers.test.ts
• apps/sim/lib/copilot/orchestrator/sse/handlers/handlers.ts
• apps/sim/lib/copilot/orchestrator/sse/handlers/tool-execution.ts
• apps/sim/lib/copilot/orchestrator/sse/utils.test.ts
• apps/sim/lib/copilot/orchestrator/sse/utils.ts
• apps/sim/lib/copilot/orchestrator/stream/core.ts
• apps/sim/lib/copilot/orchestrator/tool-executor/index.ts
• apps/sim/lib/copilot/orchestrator/types.ts
• apps/sim/lib/copilot/tools/server/files/download-to-workspace-file.ts
• apps/sim/lib/copilot/tools/server/files/workspace-file.ts
• apps/sim/lib/copilot/tools/server/image/generate-image.ts
• apps/sim/lib/copilot/tools/server/knowledge/knowledge-base.ts
• apps/sim/lib/copilot/tools/server/table/user-table.ts
• apps/sim/lib/copilot/tools/server/visualization/generate-visualization.ts
• apps/sim/lib/copilot/tools/shared/schemas.ts
• apps/sim/stores/panel/copilot/types.ts
• apps/sim/tools/shared/table.ts
• apps/sim/tools/shared/tags.ts
• apps/sim/tools/utils.test.ts
• apps/sim/tools/utils.ts

Purpose and Scope

This document describes the architectural design of the Copilot AI assistant system, including its backend orchestration, message persistence, agent-to-agent coordination, and streaming infrastructure. Copilot is an intelligent assistant that helps users build, test, deploy, and debug workflows through natural language interaction. It operates in two primary modes: Workflow Copilot (scoped to a specific workflow) and Mothership Chat (workspace-wide assistant).

For information about Copilot's context system and @-mentions, see 6.2 For details on Copilot's server-side tools, see 6.3 For information about Copilot modes and capabilities, see 6.4

---

System Overview

Copilot is a full-stack AI assistant built on a client-server architecture with three primary layers:

1. Client Layer: React UI components (e.g., MothershipChat, Panel) and hooks (useChat) that manage local message state, resource registries, and SSE stream consumption apps/sim/app/workspace/[workspaceId]/home/hooks/use-chat.ts:61-85.
2. Next.js API Layer: Orchestrates requests, handles session-based authentication, resolves workflow/workspace permissions, and manages persistence in PostgreSQL using Drizzle ORM apps/sim/app/api/copilot/chat/route.ts1-10
3. Orchestrator Layer: A specialized logic engine (orchestrateCopilotStream) that proxies requests to the Sim Agent API (Go backend), manages long-running tool executions, and handles async continuations apps/sim/lib/copilot/orchestrator/index.ts82-143

Architecture Diagram

The following diagram bridges the "Natural Language Space" (User Input) to the "Code Entity Space" (API Routes and Orchestrators).

Copilot Component Interaction

Sources: apps/sim/app/workspace/[workspaceId]/home/hooks/use-chat.ts:12-36, apps/sim/app/api/copilot/chat/route.ts111-126 apps/sim/lib/copilot/orchestrator/index.ts82-143 apps/sim/app/workspace/[workspaceId]/home/home.tsx:156-160

---

Client-Server Communication

Primary Chat APIs

The system exposes two main endpoints for interaction:

1. Workflow Copilot (/api/copilot/chat): Requires a workflowId. It resolves the workflow scope using resolveWorkflowIdForUser and processes contexts like block outputs or logs specific to that DAG apps/sim/app/api/copilot/chat/route.ts165-176
2. Mothership Chat (/api/mothership/chat): Workspace-scoped. It uses generateWorkspaceContext to provide a broader view of the environment, including information about all workflows, tables, and files apps/sim/app/api/mothership/chat/route.ts19-23

Request Lifecycle

1. Session Validation: Uses getSession() to ensure the user is authenticated apps/sim/app/api/copilot/chat/route.ts120-126
2. Context Processing: Converts @-mentions and resource attachments into text for the LLM using processContextsServer and resolveActiveResourceContext apps/sim/app/api/mothership/chat/route.ts16 apps/sim/app/api/mothership/chat/route.ts178-184
3. Stream Acquisition: Uses acquirePendingChatStream to ensure only one active stream exists per chatId, preventing race conditions apps/sim/lib/copilot/chat-streaming.ts115-119
4. Orchestration: Calls orchestrateCopilotStream to manage the interaction with the LLM and tool execution loop apps/sim/lib/copilot/orchestrator/index.ts82-85

---

Stream Management & Recovery

Copilot uses Server-Sent Events (SSE) for real-time response delivery. To handle network instability or page refreshes, it implements a persistence-based recovery system.

Distributed Locking

To prevent multiple orchestrators from writing to the same chat simultaneously, the system uses a Redis-backed lock via getChatStreamLockKey(chatId) apps/sim/lib/copilot/chat-streaming.ts59-61 Locks have a TTL of 2 hours apps/sim/lib/copilot/chat-streaming.ts21

Stream Replay and Resumption

1. Client-Side Buffer: The useChat hook maintains a list of messages and a messageQueue for optimistic updates apps/sim/app/workspace/[workspaceId]/home/hooks/use-chat.ts:61-81.
2. Snapshot Replay: If a client reconnects, it can use buildReplayStream to recreate the SSE stream from stored events apps/sim/app/workspace/[workspaceId]/home/hooks/use-chat.ts:170-186.
3. LastEventId Tracking: The client tracks the eventId of the last received message to resume from the exact point of failure apps/sim/app/workspace/[workspaceId]/home/hooks/use-chat.ts:103-107.

---

Agent Orchestration & Tool Execution

The orchestrateCopilotStream function manages a complex loop where the LLM can call tools, wait for results, and then continue generating text.

Tool Execution Model

• Server-Side Tools: Executed directly in the Next.js environment via executeToolServerSide apps/sim/lib/copilot/orchestrator/tool-executor/index.ts8-12 This includes workflow-tools (e.g., executeRunWorkflow), vfs-tools (filesystem operations), and deployment-tools apps/sim/lib/copilot/orchestrator/tool-executor/index.ts46-112
• Client-Side Tools: Tools requiring user interaction (like open_resource) are flagged as clientExecutable. The orchestrator pauses and waits for a tool_result event from the client apps/sim/lib/copilot/orchestrator/sse/handlers/handlers.ts99-112
• Async Continuations: If a tool takes too long, the orchestrator can emit an async_pause. The state is saved as a checkpoint, and execution resumes when the tool completes via a background worker apps/sim/lib/copilot/orchestrator/index.ts165-178

Sub-Agent Coordination

Copilot supports nested agents (sub-agents). The orchestrator tracks this using subagent identifiers in the SSE stream apps/sim/lib/copilot/orchestrator/sse/handlers/handlers.ts22 The UI handles these transitions by grouping blocks under specific agent labels apps/sim/app/workspace/[workspaceId]/home/components/message-content/message-content.tsx:138-169.

Tool Execution Sequence

Sources: apps/sim/lib/copilot/orchestrator/index.ts183-197 apps/sim/lib/copilot/orchestrator/sse/handlers/tool-execution.ts150-158 apps/sim/lib/copilot/orchestrator/tool-executor/index.ts108-112

---

Message Persistence & UI Rendering

Data Mapping

Messages are stored in a structured format in the database (TaskStoredMessage) and mapped to a UI-friendly format (ChatMessage) by the useChat hook apps/sim/app/workspace/[workspaceId]/home/hooks/use-chat.ts:27-36.

• Thinking Blocks: XML-like <thinking> tags are extracted and rendered as reasoning phases apps/sim/app/workspace/[workspaceId]/home/hooks/use-chat.ts:189-194.
• Tool Call Status: Mapped from internal states (success, error, cancelled) to UI statuses apps/sim/app/workspace/[workspaceId]/home/hooks/use-chat.ts:87-93.

UI Segmentation

The MessageContent component parses raw content blocks into segments:

• AgentGroup: Groups tool calls and text belonging to a specific sub-agent apps/sim/app/workspace/[workspaceId]/home/components/message-content/message-content.tsx:25-33.
• Options: Renders interactive buttons for user choices suggested by the LLM using the options tag apps/sim/app/workspace/[workspaceId]/home/components/message-content/message-content.tsx:35-38.

Sources: apps/sim/app/workspace/[workspaceId]/home/hooks/use-chat.ts:188-216, apps/sim/app/workspace/[workspaceId]/home/components/message-content/message-content.tsx:89-109, apps/sim/app/workspace/[workspaceId]/home/types.ts:1-20