Socket.IO Events

KULVEX uses Socket.IO for real-time bidirectional communication between clients and the server.

Connection

import { io } from "socket.io-client";
 
const socket = io("http://localhost:9100", {
  auth: { token: "your-jwt-token" },
});

Authenticated connections store user info in the session. Unauthenticated connections are allowed but have limited access.

Chat Events

Event	Direction	Payload	Description
`chat:send`	client → server	`{ message, task_type?, history?, use_rag?, project? }`	Send a chat message
`chat:token`	server → client	`{ token }`	Streaming token
`chat:done`	server → client	`{ response, model }`	Complete response

Example

socket.emit("chat:send", {
  message: "What's the weather?",
  task_type: "chat",
  history: [],
  use_rag: true,
});
 
socket.on("chat:token", ({ token }) => {
  process.stdout.write(token);
});
 
socket.on("chat:done", ({ response, model }) => {
  console.log(`\n[Model: ${model}]`);
});

Voice Events

Event	Direction	Payload	Description
`voice:start`	client → server	`{ language?, engine? }`	Start voice session
`voice:audio_chunk`	client → server	`{ audio }` (base64)	Audio data
`voice:stop`	client → server	`{}`	End voice session
`voice:playback_done`	client → server	`{}`	TTS playback finished
`voice:transcript`	server → client	`{ text, language }`	STT result
`voice:response`	server → client	`{ text }`	AI response
`voice:audio`	server → client	`{ audio, format }`	TTS audio

Terminal Events

Event	Direction	Payload	Description
`terminal:create`	client → server	`{ mode?, cols?, rows? }`	Create PTY session
`terminal:data`	both	`{ session_id, data }`	Terminal I/O
`terminal:resize`	client → server	`{ session_id, cols, rows }`	Resize terminal
`terminal:destroy`	client → server	`{ session_id }`	Destroy PTY

Terminal Modes

shell — Standard shell (bash/zsh)
kcode — Launches KCode interactive REPL

Disconnect Behavior

On disconnect:

Voice sessions are cleaned up immediately
Terminal PTY sessions have a 5-second grace period for reconnection before cleanup
Remote code sessions are detached from the Socket.IO sid

Endpoints Authentication