Sessions Send

Queue messages to running AI agent sessions via scorpiox-host REST API. Max 32 messages per session, 8KB each. Agents poll and drain automatically.

Overview

The scorpiox-host server (port 7432) acts as a session gateway — it tracks all running AI agent sessions and provides a message queue for inter-process communication. Any external process can push messages to a session's queue, and the agent polls and drains them automatically via SetCallback.

This enables powerful multi-agent orchestration: scripts, CI pipelines, other agents, or even iMessage/WhatsApp bridges can inject prompts directly into a running session without interrupting the current task flow.

Architecture

The message queue is an in-memory ring buffer inside scorpiox-host.c. Messages are stored per-session (max 32 slots). When an agent polls GET /sessions/:id/messages, all queued messages are returned and the buffer is drained. No persistence — if the host restarts, queued messages are lost.

How It Works

1. Session Registers

Agent starts and calls POST /sessions/:id/register with its session name. State becomes idle.

2. External Process Sends Message

Any process calls POST /sessions/:id/messages with a JSON body containing the message text (max 8KB).

3. Agent Polls Queue

The agent periodically calls GET /sessions/:id/messages. All queued messages are returned as a JSON array and the queue is drained.

4. Agent Processes Messages

Each message appears as a user prompt in the agent's conversation flow. The agent processes them sequentially.

API Endpoints

POST /sessions/:id/messages

Queue a message — pushes a message to the session's queue. Returns 429 if queue full (32 messages).

Parameter	Type	In	Description
id	string	path	Session ID (required)
message	string	body	Message text, max 8192 bytes (required)

GET /sessions/:id/messages

Pull queued messages — returns and drains the message queue for a session. Returns JSON array of message strings.

Parameter	Type	In	Description
id	string	path	Session ID (required)

GET /sessions

List all sessions — returns JSON array with id, state, last_event timestamp, event_count, and optional model/provider metadata. Use this to discover session IDs before sending.

POST /sessions/:id/register

Register a session — creates or updates a session with a display name, sets state to idle. Call this before sending messages to ensure the session exists.

Parameter	Type	In	Description
id	string	path	Session ID (required)
session	string	body	Human-readable session name (optional)

Configuration

Add these to your scorpiox-env.txt to enable session tracking and message queue functionality:

# Enable session event emission (required for agent tracking)
EMIT_SESSION_TRACKING=1

# API endpoint for session event data (scorpiox-host address)
EMIT_SESSION_API_URL=http://localhost:7432

# Days to retain session logs (default: 7)
SESSION_RETENTION_DAYS=7

The scorpiox-host server runs on port 7432 by default. Start it with:

# Start scorpiox-host daemon
scorpiox-host --daemon

# Or run in foreground for debugging
scorpiox-host --port 7432

Examples

Send a message via curl

# List active sessions to find the ID
curl -s http://localhost:7432/sessions | jq '.[].id'

# Send a message to a specific session
curl -X POST http://localhost:7432/sessions/abc123/messages \
  -H "Content-Type: application/json" \
  -d '{"message": "Run the test suite and report failures"}'

Send from a CI pipeline

#!/bin/bash
# notify-agent.sh — send build results to the coding agent
SESSION_ID="${SCORPIOX_SESSION_ID}"
HOST="http://localhost:7432"

if [ "$CI_STATUS" = "failed" ]; then
  curl -sX POST "$HOST/sessions/$SESSION_ID/messages" \
    -H "Content-Type: application/json" \
    -d '{"message": "Build failed on '"$CI_BRANCH"': '"$CI_ERROR"'. Please fix."}'
fi

Send from Python

import requests

HOST = "http://localhost:7432"
SESSION = "abc123"

# Queue a task for the agent
requests.post(f"{HOST}/sessions/{SESSION}/messages", json={
    "message": "Refactor the auth module to use JWT tokens"
})

Poll messages (agent-side)

# Agent polls and drains its queue
curl -s http://localhost:7432/sessions/abc123/messages
# Response: ["Run the test suite", "Fix the auth bug"]
# Queue is now empty

Limits & Error Codes

Max Queue Depth

32 messages

Max Message Size

8,192 bytes

Default Port

7432

Persistence

None (in-memory)

Error Responses

200 Message queued successfully

404 Session not found — the session ID doesn't exist or hasn't registered

429 Queue full — session has 32 pending messages, try again later

413 Message too large — exceeds 8KB limit