Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ The interface hive, quorum and spektacular build against is [docs/contract.md](d
Quorum is a child process inside the hive container, like the `spektacular` binary. It listens on loopback only; no extra container or pod change is needed.

1. Hive writes a fresh random bearer token to a file at boot, and the tenant's Vexa API key (and, if used, the Discord bot token) from its keystore to files.
2. Hive starts `node quorum.mjs serve` with the `QUORUM_*` variables below and supervises it. `GET /healthz` answers `{"ok":true,...}` once it is listening.
2. Hive starts `node quorum.mjs serve` with the `QUORUM_*` variables below and supervises it. `GET /healthz` answers `{"ok":true,...}` once it is listening. `GET /metrics` (same bearer) serves Prometheus metrics for tool calls, upstream services and adapter connectivity; see [docs/contract.md](docs/contract.md#metrics).
3. Hive is the MCP client: `POST http://127.0.0.1:8765/mcp` with `Authorization: Bearer <token>` (streamable HTTP, stateless, JSON responses). Tools: `meeting.join`, `meeting.leave`, `meeting.status`, `transcript.read`, `chat.post`, `say`, `say.tone` (the soft listening chime: played by the Vexa bot, by quorum itself on Discord, and by the desktop companion on the host's computer), `say.prewarm`, `meeting.delete`. Every result is `{ok:true,...}` or `{ok:false,error:{code,message}}` in `structuredContent` and as JSON text.
4. Hive follows each meeting on `GET /events?meeting_id=<id>` (Server-Sent Events, same bearer): `segment`, `chat` and `state` events, one JSON object per `data:` line, `id:` = `seq`. Reconnect with `after_seq=<last seq>` to replay what was missed. `GET /events` without `meeting_id` carries every meeting, including Discord `/hive join` requests.
5. On SIGTERM quorum leaves Discord channels and exits. Vexa bots keep running until hive calls `meeting.leave`; a restarted quorum that is asked to join the same meeting adopts the running bot.
Expand Down
16 changes: 15 additions & 1 deletion docs/contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Three boundaries, versioned together. Every component in hive, quorum and spekta
Quorum runs **inside the hive container** as a child process that hive starts and supervises, the same way hive runs the `spektacular` binary. It listens on loopback only. No extra container, no pod spec change, no hub change.

- Binary: `quorum serve` (Node 22, published as `@hivecommons/quorum` and baked into the hive image).
- Listen: `QUORUM_LISTEN` (default `127.0.0.1:8765`). MCP endpoint `POST /mcp` (streamable HTTP). Health `GET /healthz`.
- Listen: `QUORUM_LISTEN` (default `127.0.0.1:8765`). MCP endpoint `POST /mcp` (streamable HTTP). Health `GET /healthz`. Metrics `GET /metrics` (bearer, Prometheus text; see Metrics below).
- Auth: bearer token from `QUORUM_TOKEN_FILE`, generated by hive per boot and passed to the child.
- Vexa: `QUORUM_VEXA_URL` (gateway base URL), `QUORUM_VEXA_API_KEY_FILE` (tenant key; hive writes it from its keystore).
- Discord: `QUORUM_DISCORD_TOKEN_FILE` (per-hive bot token, optional; Discord tools return `platform_unavailable` without it).
Expand Down Expand Up @@ -90,3 +90,17 @@ Behaviour targets: act on final segments only; ask at pauses longer than `SPEK_M
- `GET /api/meetings/{id}/ws` live panel: transcript, intents, research status.
- Research: each `research` intent becomes a kick to the research agent pool with a kick ID; `[FINDING]` and `[COMPLETE]` signals for that kick come back as `research_update` to Spek and a `chat.post` summary (max one per research item) plus a knowledge fact under the meeting's notes.
- On join hive posts the consent notice (`meetings.consent_text`) before anything else. `hive leave` typed in chat or said to hive makes it leave.

## Metrics

`GET /metrics` serves Prometheus text format on the same loopback listener, with the same bearer as `/mcp` and `/events` (401 without it). Nothing is pushed anywhere; a scraper on the host pulls it. Label values come from fixed sets, never from caller input: no meeting ids, user ids, URLs or error strings.

| Metric | Type | Labels |
|---|---|---|
| `quorum_tool_calls_total` | counter | `tool` (a tool in section 1; any other name is `unknown`), `outcome` (`ok`, `error`) |
| `quorum_tool_call_duration_seconds` | histogram | `tool` |
| `quorum_upstream_requests_total` | counter | `service` (`transcribe`, `tts`, `vexa`), `outcome` (`ok` for a 2xx answer, `error` otherwise, timeouts and unreachable included) |
| `quorum_upstream_duration_seconds` | histogram | `service` |
| `quorum_adapter_connected` | gauge | `adapter` (`discord`, `vexa`, `companion`): 1 when the adapter can serve meetings |

Each HTTP request counts, so a transcription call retried three times is three requests. `quorum_adapter_connected` is read at scrape time: Discord is 1 once the gateway login finished; Vexa is 1 while its websocket is open or while no meeting is followed (the socket only exists for live meetings); the companion is 1 when `QUORUM_TRANSCRIBE_URL` is set. An adapter that is not configured has no series. Counters reset when quorum restarts.
25 changes: 21 additions & 4 deletions src/app.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import type { PlatformAdapter } from "./adapter.js";
import { readSecretFile, type Config } from "./config.js";
import { createHttpServer } from "./http.js";
import type { Logger } from "./log.js";
import { Metrics } from "./metrics.js";
import { Registry, type Platform } from "./meeting.js";
import { Quorum } from "./service.js";
import { companionAdapter } from "./companion/index.js";
Expand All @@ -28,7 +29,12 @@ export type AdapterFactory = (ctx: {
config: Config;
registry: Registry;
log: Logger;
}) => Promise<Partial<Record<Platform, PlatformAdapter & { close?: () => Promise<void> }>>>;
metrics?: Metrics;
}) => Promise<
Partial<
Record<Platform, PlatformAdapter & { close?: () => Promise<void>; connected?: () => boolean }>
>
>;

export async function startQuorum(
config: Config,
Expand All @@ -44,6 +50,7 @@ export async function startQuorum(
},
);
}
const metrics = new Metrics();
const registry = new Registry(config.meetingRetentionS * MS_PER_S);
const adapters: Partial<Record<Platform, PlatformAdapter & { close?: () => Promise<void> }>> = {};
let stream: VexaStream | undefined;
Expand All @@ -54,6 +61,7 @@ export async function startQuorum(
baseUrl: config.vexaUrl,
apiKey,
timeoutMs: config.vexaTimeoutMs,
metrics,
});
stream = new VexaStream({
baseUrl: config.vexaUrl,
Expand All @@ -78,17 +86,26 @@ export async function startQuorum(
adapters.google_meet = vexa;
adapters.teams = vexa;
adapters.zoom = vexa;
// The gateway socket only exists while a meeting is followed, so idle counts as connected.
const followed = stream;
metrics.adapter("vexa", () => followed.connected || followed.subscriptions === 0);
} else {
log.info("QUORUM_VEXA_URL is unset: Meet, Teams and Zoom answer platform_unavailable");
}
const companion = companionAdapter(config, log);
const companion = companionAdapter(config, log, metrics);
adapters.companion = companion;
metrics.adapter("companion", () => companion.connected());
if (extraAdapters) {
Object.assign(adapters, await extraAdapters({ config, registry, log }));
const extra = await extraAdapters({ config, registry, log, metrics });
Object.assign(adapters, extra);
const discord = extra.discord;
if (discord?.connected) {
metrics.adapter("discord", () => discord.connected?.() ?? false);
}
}

const quorum = new Quorum({ config, registry, adapters, log });
const server = createHttpServer({ quorum, config, log, token, companion });
const server = createHttpServer({ quorum, config, log, token, companion, metrics });
await new Promise<void>((resolve, reject) => {
server.once("error", reject);
server.listen(config.port, config.host, () => {
Expand Down
5 changes: 5 additions & 0 deletions src/companion/adapter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,11 @@ export class CompanionAdapter implements PlatformAdapter {
this.now = opts.now ?? Date.now;
}

/** For quorum_adapter_connected: whether a join can succeed (audio can be transcribed). */
connected(): boolean {
return this.opts.transcriber !== undefined;
}

async join(meeting: Meeting, args: JoinArgs): Promise<void> {
if (!this.opts.transcriber) {
throw new QuorumError(
Expand Down
4 changes: 3 additions & 1 deletion src/companion/index.ts
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
import { readSecretFile, type Config } from "../config.js";
import { Transcriber } from "../discord/transcribe.js";
import type { Logger } from "../log.js";
import type { Metrics } from "../metrics.js";
import { CompanionAdapter } from "./adapter.js";

/**
* The companion platform is always registered: it only listens on quorum's own loopback HTTP
* surface. Without QUORUM_TRANSCRIBE_URL a companion join answers platform_unavailable.
*/
export function companionAdapter(config: Config, log: Logger): CompanionAdapter {
export function companionAdapter(config: Config, log: Logger, metrics?: Metrics): CompanionAdapter {
const transcriber = config.transcribeUrl
? new Transcriber({
url: config.transcribeUrl,
Expand All @@ -17,6 +18,7 @@ export function companionAdapter(config: Config, log: Logger): CompanionAdapter
: undefined,
...(config.transcribeLanguage ? { language: config.transcribeLanguage } : {}),
timeoutMs: config.transcribeTimeoutMs,
...(metrics ? { metrics } : {}),
hotwords: config.transcribeHotwords,
retry: {
maxAttempts: config.transcribeMaxAttempts,
Expand Down
5 changes: 5 additions & 0 deletions src/discord/adapter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,11 @@ export class DiscordAdapter implements PlatformAdapter {
return this.ready;
}

/** For quorum_adapter_connected: the gateway login finished. */
connected(): boolean {
return this.ready;
}

/**
* Logs in and registers the /hive command. Resolves once the client is ready. Typed chat needs
* the privileged MessageContent intent; when Discord refuses it, quorum logs that once and logs
Expand Down
4 changes: 3 additions & 1 deletion src/discord/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import type { DiscordRuntime } from "./types.js";
export function discordAdapters(
load: () => Promise<DiscordRuntime> = loadDiscordRuntime,
): AdapterFactory {
return async ({ config, registry, log }) => {
return async ({ config, registry, log, metrics }) => {
if (!config.discordTokenFile) {
return {};
}
Expand All @@ -35,6 +35,7 @@ export function discordAdapters(
: undefined,
...(config.transcribeLanguage ? { language: config.transcribeLanguage } : {}),
timeoutMs: config.transcribeTimeoutMs,
...(metrics ? { metrics } : {}),
hotwords: config.transcribeHotwords,
retry: {
maxAttempts: config.transcribeMaxAttempts,
Expand All @@ -51,6 +52,7 @@ export function discordAdapters(
? readSecretFile(config.ttsTokenFile, "QUORUM_TTS_TOKEN_FILE")
: undefined,
timeoutMs: config.ttsTimeoutMs,
...(metrics ? { metrics } : {}),
})
: undefined;
const adapter = new DiscordAdapter({ runtime, registry, log, config, transcriber, tts });
Expand Down
7 changes: 6 additions & 1 deletion src/discord/transcribe.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import { QuorumError } from "../errors.js";
import { timedUpstream, type Metrics } from "../metrics.js";

/**
* Client for the shared CPU transcription service (hivecommons/vexa
Expand Down Expand Up @@ -48,6 +49,8 @@ export interface TranscriberOptions {
/** Vocabulary for every request (QUORUM_TRANSCRIBE_HOTWORDS), after the per-call hints. */
hotwords?: string[];
retry?: Partial<RetryPolicy>;
/** Records each request to the service in quorum_upstream_* (service="transcribe"). */
metrics?: Metrics;
fetchImpl?: typeof fetch;
sleep?: (ms: number) => Promise<void>;
/** Uniform [0, 1); the jitter source. */
Expand Down Expand Up @@ -178,7 +181,9 @@ export class Transcriber {
const maxAttempts = Math.max(1, Math.floor(call.maxAttempts ?? this.retry.maxAttempts));
for (let attempt = 1; ; attempt++) {
try {
return await this.once(wav, prompt, hotwords);
return await timedUpstream(this.opts.metrics, "transcribe", () =>
this.once(wav, prompt, hotwords),
);
} catch (err) {
if (!(err instanceof Retryable)) {
throw err;
Expand Down
9 changes: 8 additions & 1 deletion src/discord/tts.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import { QuorumError } from "../errors.js";
import { timedUpstream, type Metrics } from "../metrics.js";

/**
* Client for the shared Kokoro TTS service: OpenAI-compatible `POST /v1/audio/speech` with
Expand All @@ -16,6 +17,8 @@ export interface TtsClientOptions {
url: string;
token: () => string | undefined;
timeoutMs: number;
/** Records each request to the service in quorum_upstream_* (service="tts"). */
metrics?: Metrics;
fetchImpl?: typeof fetch;
}

Expand All @@ -32,7 +35,11 @@ export class TtsClient {
}

/** Synthesizes `text` and returns 24 kHz s16le mono PCM. Failures are `upstream_error`. */
async synthesize(text: string, voice: string): Promise<Buffer> {
synthesize(text: string, voice: string): Promise<Buffer> {
return timedUpstream(this.opts.metrics, "tts", () => this.request(text, voice));
}

private async request(text: string, voice: string): Promise<Buffer> {
const headers: Record<string, string> = { "Content-Type": "application/json" };
const token = this.opts.token();
if (token) {
Expand Down
18 changes: 15 additions & 3 deletions src/http.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,16 @@ import { ChunkGapError, isCompanionChannel, type CompanionAdapter } from "./comp
import type { Config } from "./config.js";
import { QuorumError } from "./errors.js";
import type { Logger } from "./log.js";
import type { Metrics } from "./metrics.js";
import type { QuorumEvent, StateEvent } from "./meeting.js";
import { createMcpServer } from "./mcp.js";
import type { Quorum } from "./service.js";
import { CONTRACT_VERSION, VERSION } from "./version.js";

/**
* The loopback HTTP surface: `GET /healthz` (no auth), `POST /mcp` (MCP streamable HTTP,
* stateless, JSON responses), `GET /events` (Server-Sent Events), and the companion platform's
* stateless, JSON responses), `GET /events` (Server-Sent Events), `GET /metrics` (Prometheus
* text), and the companion platform's
* `POST /companion/audio` and `GET /companion/outbox`. Everything except /healthz needs
* `Authorization: Bearer <token>`.
*/
Expand Down Expand Up @@ -89,10 +91,11 @@ export interface HttpOptions {
log: Logger;
token: string;
companion?: CompanionAdapter;
metrics?: Metrics;
}

export function createHttpServer(opts: HttpOptions): Server {
const { quorum, config, log, token, companion } = opts;
const { quorum, config, log, token, companion, metrics } = opts;

async function handleMcp(req: IncomingMessage, res: ServerResponse): Promise<void> {
if (req.method !== "POST") {
Expand Down Expand Up @@ -120,7 +123,7 @@ export function createHttpServer(opts: HttpOptions): Server {
});
return;
}
const server = createMcpServer(quorum, log);
const server = createMcpServer(quorum, log, metrics);
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: undefined,
enableJsonResponse: true,
Expand Down Expand Up @@ -320,6 +323,15 @@ export function createHttpServer(opts: HttpOptions): Server {
});
return;
}
if (metrics && url.pathname === "/metrics") {
if (req.method !== "GET") {
sendJson(res, HTTP_METHOD_NOT_ALLOWED, { error: "GET only" }, { Allow: "GET" });
return;
}
res.writeHead(HTTP_OK, { "Content-Type": "text/plain; version=0.0.4; charset=utf-8" });
res.end(metrics.render());
return;
}
if (url.pathname === "/events") {
handleEvents(req, res, url);
return;
Expand Down
14 changes: 11 additions & 3 deletions src/mcp.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
import { failure, type ToolResult } from "./errors.js";
import type { Logger } from "./log.js";
import { silentLogger } from "./log.js";
import type { Metrics } from "./metrics.js";
import type { Quorum } from "./service.js";
import { VERSION } from "./version.js";

Expand Down Expand Up @@ -157,6 +158,11 @@ export function callTool(q: Quorum, name: string, args: unknown): Promise<ToolRe

const TOOL_NAMES: ReadonlySet<string> = new Set(TOOLS.map((t) => t.name));

/** The tool name as a bounded label value: a contract tool, or "unknown" for anything else. */
export function boundedToolName(name: string): string {
return TOOL_NAMES.has(name) ? name : "unknown";
}

/**
* One log line per tool call: tool, outcome, error code and duration. The tool name comes from
* the client, so anything outside the contract list is logged as "unknown" to keep the value
Expand All @@ -169,7 +175,7 @@ export function logToolCall(
durationMs: number,
): void {
const fields = {
tool: TOOL_NAMES.has(name) ? name : "unknown",
tool: boundedToolName(name),
ok: result.ok,
...(result.ok ? {} : { error_code: result.error.code }),
duration_ms: Math.round(durationMs),
Expand All @@ -181,13 +187,15 @@ export function logToolCall(
}
}

export function createMcpServer(q: Quorum, log: Logger = silentLogger): Server {
export function createMcpServer(q: Quorum, log: Logger = silentLogger, metrics?: Metrics): Server {
const server = new Server({ name: "quorum", version: VERSION }, { capabilities: { tools: {} } });
server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: TOOLS.map((t) => ({ ...t })) }));
server.setRequestHandler(CallToolRequestSchema, async (req) => {
const started = performance.now();
const result = await callTool(q, req.params.name, req.params.arguments);
logToolCall(log, req.params.name, result, performance.now() - started);
const durationMs = performance.now() - started;
logToolCall(log, req.params.name, result, durationMs);
metrics?.toolCall(boundedToolName(req.params.name), result.ok ? "ok" : "error", durationMs);
return {
content: [{ type: "text", text: JSON.stringify(result) }],
structuredContent: result as unknown as Record<string, unknown>,
Expand Down
Loading