WebSocket API

Connection URL: ws://localhost:3777/ws

The WebSocket connection is used for real-time chat with the agent. All messages are JSON-encoded strings.

---

Incoming Events (Client to Server)

chat

Start or continue a conversation.

{
  "type": "chat",
  "sessionKey": "unique-session-id",
  "message": "Your message here",
  "workspaceId": "workspace-id",
  "attachments": [
    {
      "mimeType": "image/png",
      "base64": "...",
      "name": "screenshot.png"
    }
  ],
  "fileReferences": ["path/to/file.txt"]
}

Field	Type	Required	Description
sessionKey	string	yes	Unique session identifier
message	string	yes	User message text
workspaceId	string	yes	Target workspace ID
attachments	array	no	Base64-encoded file attachments
fileReferences	array	no	Workspace file paths to include as context

cancel

Abort a running agent session.

{
  "type": "cancel",
  "sessionKey": "unique-session-id"
}

permission_response

Respond to a permission request from the agent.

{
  "type": "permission_response",
  "requestId": "request-id",
  "approved": true
}

questionnaire_response

Submit answers to a questionnaire requested by the agent.

{
  "type": "questionnaire_response",
  "requestId": "request-id",
  "responses": {
    "question_id": "answer",
    "multi_question_id": ["option1", "option2"]
  }
}

---

Outgoing Events (Server to Client)

thinking_delta

Streamed thinking/reasoning text from the model.

{
  "type": "thinking_delta",
  "sessionKey": "...",
  "text": "partial thinking text"
}

text_delta

Streamed response text from the model.

{
  "type": "text_delta",
  "sessionKey": "...",
  "text": "partial response text"
}

tool_call_start

Indicates a tool invocation has begun.

{
  "type": "tool_call_start",
  "sessionKey": "...",
  "toolName": "read_file",
  "toolCallId": "call-id"
}

tool_call_delta

Streamed partial tool call arguments (sent during argument generation).

tool_call_end

Indicates tool call argument generation is complete.

tool_result

The result of a tool execution.

{
  "type": "tool_result",
  "sessionKey": "...",
  "toolCallId": "call-id",
  "toolName": "read_file",
  "toolArgs": { "path": "src/index.ts" },
  "content": "file contents...",
  "isError": false
}

permission_request

The agent needs user approval to proceed with a sensitive action.

{
  "type": "permission_request",
  "requestId": "request-id",
  "description": "Execute command: npm install",
  "details": "optional details"
}

Respond with a permission_response message. Auto-denied after 60 seconds.

questionnaire_request

The agent wants to collect structured input from the user.

{
  "type": "questionnaire_request",
  "requestId": "request-id",
  "data": {
    "title": "Project Setup",
    "description": "...",
    "questions": [
      {
        "id": "framework",
        "question": "Which framework?",
        "type": "single",
        "options": [
          { "value": "react", "label": "React" },
          { "value": "vue", "label": "Vue" }
        ]
      }
    ]
  }
}

done

The agent run has completed.

{
  "type": "done",
  "sessionKey": "...",
  "usage": {
    "inputTokens": 1234,
    "outputTokens": 567
  }
}

error

An error occurred during the agent run.

{
  "type": "error",
  "sessionKey": "...",
  "error": "Error message"
}

channel:status

Broadcast when a channel adapter starts or stops.

{
  "type": "channel:status",
  "channelId": "telegram",
  "running": true,
  "authenticated": true
}

session:refresh

Broadcast when a session is updated from a channel (signals the UI to refresh the session list).

{
  "type": "session:refresh",
  "workspaceId": "workspace-id"
}

---

Connection Behavior

• CORS is restricted to local origins (localhost, 127.0.0.1) by default. Set CORTASK_CORS_ORIGIN to allow additional origins.
• When a client disconnects, all active runs for that client are aborted and all pending permission requests are auto-denied.
• Pending questionnaire requests are not auto-denied on disconnect, allowing the user to reconnect and submit.