@ariaflowagents/hono-server

Hono router for hosting AriaFlow Runtime and flow managers over HTTP + WebSocket.

Usage (Node.js)

import { Hono } from 'hono';
import { serve } from '@hono/node-server';
import { createNodeWebSocket } from '@hono/node-ws';
import { Runtime } from '@ariaflowagents/core';
import { createAriaChatRouter } from '@ariaflowagents/hono-server';

const app = new Hono();
const { upgradeWebSocket, injectWebSocket } = createNodeWebSocket({ app });

const runtime = new Runtime({
  agents: [],
  defaultAgentId: 'triage',
});

app.route('/', createAriaChatRouter({ runtime, upgradeWebSocket }));

const server = serve({ fetch: app.fetch, port: 3000 });
injectWebSocket(server);

Usage (Bun)

import { Hono } from 'hono';
import { upgradeWebSocket } from 'hono/bun';
import { Runtime } from '@ariaflowagents/core';
import { createAriaChatRouter } from '@ariaflowagents/hono-server';

const app = new Hono();

const runtime = new Runtime({
  agents: [],
  defaultAgentId: 'triage',
});

app.route('/', createAriaChatRouter({ runtime, upgradeWebSocket }));

export default app;

Widget Welcome Behavior

createAriaChatRouter supports deterministic first-turn behavior for widget sockets (/agents/chat/:sessionId):

app.route('/', createAriaChatRouter({
  runtime,
  upgradeWebSocket,
  widgetWelcomeMode: 'static', // 'off' | 'model' | 'static'
  widgetWelcomeMessage: "I'm the virtual assistant. How can I help?",
  widgetWelcomeSuggestions: [
    'Check Availability',
    'Book Appointment',
    'Inquiries',
  ], // optional
}));

Modes

• off: no welcome turn on socket connect
• model: welcome generated via runtime.stream(...)
• static: send widgetWelcomeMessage directly (no model call)

sendWidgetWelcomeMessage is still accepted for backward compatibility, but widgetWelcomeMode is recommended.

Flow Support

For structured conversation flows, use createAriaFlowRouter:

import { FlowManager } from '@ariaflowagents/core';
import { createAriaFlowRouter } from '@ariaflowagents/hono-server';

const flowManager = new FlowManager({
  initialNode: 'greeting',
  nodes: [...],
  model: ...,
});

app.route('/', createAriaFlowRouter({
  flowManager,
  sessionId: 'flow-session',
  upgradeWebSocket,
}));

Examples

• examples/basic-server (Node.js) - Runtime example
• examples/bun-server (Bun) - Runtime example
• examples/flow-server (Node.js) - Flow example

Runtime Routes

• GET /health
• POST /api/chat
• POST /api/chat/stream
• POST /api/chat/sse
• GET /api/session/:id
• DELETE /api/session/:id
• GET /ws/:sessionId

Flow Routes

• GET /health
• GET /info
• GET /flow-state
• POST /api/flow/chat
• POST /api/flow/stream
• POST /api/flow/sse
• GET /ws