Event Protocol

Overview

HUMA uses a bidirectional event protocol over WebSocket. Clients send events to inform the agent about state changes and tool results. The server sends events when the agent wants to take action or communicate.

Transport

All communication uses Socket.IO over WebSocket.

socket.emit('message', )

socket.on('event', handler)  // tool-call, messaging
socket.on('error', handler)  // error events

Client Events

Every client event is a JSON object sent via socket.emit('message', event). There are exactly three event types.

context-update

Pushes new context to the HUMA agent. This is the primary way to inform the agent about what is happening in the client application.

socket.emit('message', {
  type: 'context-update',
  triggering: true,
  name: 'new-message',
  context: {
    group: { id: 'group-123', name: 'Movie Night' },
    members: [
      { name: 'Alice', id: 'user-1' },
      { name: 'Bob', id: 'user-2' }
    ],
    conversationHistory: '[14:30] Alice: What movie should we watch?'
  },
  description: 'Alice sent a message: "What movie should we watch?"'
})

The triggering Field

Examples

{
  type: 'context-update',
  triggering: true,
  name: 'new-message',
  context: {
    group: { id: 'group-123', name: 'Movie Night' },
    conversationHistory: '[14:30] Alice: What movie?\n[14:31] Bob: Something fun'
  },
  description: 'Bob sent a message: "Something fun"'
}

{
  type: 'context-update',
  triggering: false,
  name: 'new-message',
  context: {
    group: { id: 'group-123', name: 'Movie Night' },
    conversationHistory: '[14:30] Alice: What movie should we watch?'
  },
  description: 'You joined the group'
}

tool-result

Returns the result of a tool call that the agent previously requested via a tool-call server event.

socket.emit('message', {
  type: 'tool-result',
  triggering: true,
  toolCallId: '550e8400-e29b-41d4-a716-446655440000',
  toolName: 'lookup_movie',
  outcome: 'success',
  result: { title: 'Inception', year: 2010, rating: 8.8 }
})

The outcome Field

The triggering Field in Tool Results

Examples

{
  type: 'tool-result',
  triggering: true,
  toolCallId: '550e8400-e29b-41d4-a716-446655440000',
  toolName: 'lookup_movie',
  outcome: 'success',
  result: '{"title":"Inception","year":2010,"rating":8.8}'
}

{
  type: 'tool-result',
  triggering: true,
  toolCallId: '550e8400-e29b-41d4-a716-446655440000',
  toolName: 'lookup_movie',
  outcome: 'failure',
  error: 'Movie not found: Nonexistent Movie'
}

{
  type: 'tool-result',
  triggering: false,
  toolCallId: '550e8400-e29b-41d4-a716-446655440000',
  toolName: 'lookup_movie',
  outcome: 'canceled'
}

{
  type: 'tool-result',
  triggering: false,
  toolCallId: '660e8400-e29b-41d4-a716-446655440001',
  toolName: 'update_preferences',
  outcome: 'success',
  result: 'Preferences updated for Alice'
}

addon-tool-event

Sends data back to a server-side addon tool during its execution. This is not a final result — it is an in-flight data exchange. The most common use case is confirming message delivery from the messaging addon.

socket.emit('message', {
  type: 'addon-tool-event',
  toolCallId: '770e8400-e29b-41d4-a716-446655440002',
  data: {
    messageIndex: 0,
    success: true,
    context: {
      conversationHistory: '[14:30] Alice: What movie?\n[14:31] Agent: How about Inception?'
    }
  }
})

Messaging Addon Confirmation

When confirming message delivery from the messaging addon, the data field contains:

{
  type: 'addon-tool-event',
  toolCallId: '',
  data: {
    messageIndex: 0,
    success: true,
    context: {
      conversationHistory: '...'
    }
  }
}

{
  type: 'addon-tool-event',
  toolCallId: '',
  data: {
    messageIndex: 0,
    success: false,
    error: 'Failed to send: rate limited'
  }
}

Server Events

All server events arrive on the "event" Socket.IO channel: socket.on('event', handler). Each event is a JSON object with a type field.

tool-call

The agent is requesting the client to execute a tool.

{
  type: 'tool-call',
  toolCallId: '550e8400-e29b-41d4-a716-446655440000',
  toolName: 'lookup_movie',
  arguments: {
    title: 'Inception',
    year: 2010
  }
}

Client Responsibility

If the tool is unknown, send a failed result:

{
  type: 'tool-result',
  triggering: true,
  toolCallId: '',
  toolName: '',
  outcome: 'failure',
  error: 'Unknown tool: '
}

cancel-tool-call

The agent is requesting cancellation of a previously issued tool call. This happens when the agent is interrupted (e.g., a new triggering event arrives while a tool is still executing).

{
  type: 'cancel-tool-call',
  toolCallId: '550e8400-e29b-41d4-a716-446655440000',
  toolName: 'lookup_movie',
  reason: 'canceled by agent'
}

Client Responsibility

Abort the in-flight tool execution if possible, then send a canceled result:

{
  type: 'tool-result',
  triggering: false,
  toolCallId: '',
  toolName: '',
  outcome: 'canceled'
}

messaging

Events from the messaging addon. This addon handles the agent's message-sending lifecycle with realistic typing delays.

Messaging Lifecycle

The full lifecycle for a burst of N messages:

Client Responsibilities

socket.emit('message', {
  type: 'addon-tool-event',
  toolCallId: data.toolCallId,
  data: {
    messageIndex: data.messageIndex,
    success: true,
    context: { conversationHistory: '...' }
  }
})

error

Server-side error. Arrives on the "error" Socket.IO channel: socket.on('error', handler).

{
  type: 'error',
  message: 'context-update requires boolean "triggering"',
  code: 'INVALID_EVENT'
}

Validation Limits