@aexol/spectral 0.0.1

package/dist/extensions/aexol-mcp.js

@@ -0,0 +1,117 @@
+/**
+ * Aexol MCP pi extension.
+ *
+ * Loaded by the spectral wrapper via `--extension <abs-path>`. On startup it:
+ *   1. Reads ~/.spectral/config.json (writen by `spectral login`).
+ *   2. Calls tools/list against the MCP backend once.
+ *   3. Registers every returned tool through pi.registerTool() so the model
+ *      can call them like built-in tools.
+ *
+ * Each registered tool is just a thin proxy: when pi's model invokes it, we
+ * translate the call into a JSON-RPC tools/call POST and unwrap the response
+ * into the `{ content: [{ type: "text", text }], details }` shape pi expects.
+ *
+ * Failure modes are intentionally non-fatal: if config is missing or the
+ * backend is unreachable we log a warning and return, leaving pi to start
+ * without Aexol tools rather than crashing the whole agent.
+ */
+import { getApiUrl, readConfig } from "../config.js";
+import { AexolMcpClient, AexolMcpError } from "../mcp-client.js";
+/**
+ * Render a backend tool result into a single string for pi.
+ *
+ * The Aexol backend wraps results as `{ content: [{ type: "json", json: ... }] }`
+ * but may also send `{ type: "text", text: ... }`. We pick the first content
+ * item, prefer JSON when present (pretty-print so the model can read it),
+ * fall back to text, and last-resort stringify the whole content array.
+ */
+function renderContentToString(content) {
+    if (content.length === 0)
+        return "";
+    const first = content[0];
+    if (first.json !== undefined) {
+        try {
+            return JSON.stringify(first.json, null, 2);
+        }
+        catch {
+            return String(first.json);
+        }
+    }
+    if (typeof first.text === "string")
+        return first.text;
+    try {
+        return JSON.stringify(content, null, 2);
+    }
+    catch {
+        return String(content);
+    }
+}
+/** Build a one-line human label from a tool name like "remote_cloud_search". */
+function toLabel(name) {
+    return name
+        .split(/[_\s-]+/)
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ") || name;
+}
+export default async function aexolMcpExtension(pi) {
+    const cfg = await readConfig();
+    if (!cfg) {
+        // Pre-flight in cli.ts should have caught this. Logging is enough.
+        process.stderr.write("[aexol-mcp] No ~/.spectral/config.json found; Aexol tools disabled. Run `spectral login`.\n");
+        return;
+    }
+    const apiUrl = getApiUrl(cfg.apiUrl);
+    const client = new AexolMcpClient(apiUrl, cfg.teamApiKey);
+    let tools;
+    try {
+        tools = await client.listTools();
+    }
+    catch (err) {
+        const msg = err instanceof AexolMcpError || err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[aexol-mcp] Failed to fetch tool catalog from ${apiUrl}: ${msg}\n`);
+        process.stderr.write("[aexol-mcp] Continuing without Aexol tools.\n");
+        return;
+    }
+    let registered = 0;
+    for (const tool of tools) {
+        // Defensive defaults: an empty-object schema is valid JSON Schema and
+        // will pass the agent's validator if the model sends `{}`.
+        const parameters = (tool.inputSchema ?? { type: "object", properties: {} });
+        const definition = {
+            name: tool.name,
+            label: toLabel(tool.name),
+            description: tool.description ?? "",
+            parameters,
+            async execute(_toolCallId, params) {
+                const res = await client.callTool(tool.name, params);
+                const text = renderContentToString(res.content);
+                if (res.isError === true) {
+                    // Surface backend tool errors as a textual result, not a thrown
+                    // exception. Pi treats this as the tool's natural reply; the model
+                    // sees the `[Aexol MCP error] ...` marker and can recover. Throwing
+                    // here would force pi to wrap the message and risk crashing
+                    // callers that don't expect agent-tool exceptions.
+                    const errorText = `[Aexol MCP error] ${text || "Tool reported an error with no message."}`;
+                    return {
+                        content: [{ type: "text", text: errorText }],
+                        details: { isError: true },
+                    };
+                }
+                return {
+                    content: [{ type: "text", text }],
+                    details: {},
+                };
+            },
+        };
+        try {
+            pi.registerTool(definition);
+            registered++;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[aexol-mcp] Failed to register tool "${tool.name}": ${msg}\n`);
+        }
+    }
+    process.stderr.write(`[aexol-mcp] Registered ${registered} Aexol MCP tool(s) from ${apiUrl}.\n`);
+}

package/dist/mcp-client.js

@@ -0,0 +1,116 @@
+/**
+ * Minimal hand-rolled JSON-RPC 2.0 client for the Aexol MCP backend.
+ *
+ * Why hand-rolled, not @modelcontextprotocol/sdk?
+ *  - The Aexol backend speaks a non-standard MCP dialect (custom content types,
+ *    protocol version 0.1.0 negotiation, no SSE). The official SDK adds a lot
+ *    of negotiation overhead we don't need and would actively break against
+ *    this server.
+ *  - All we want is: POST a JSON-RPC envelope with a Bearer token, get a
+ *    JSON-RPC reply, surface errors. fetch() is built into Node 20+.
+ */
+/**
+ * Errors thrown by AexolMcpClient carry an optional HTTP `status` so callers
+ * can produce friendlier messages (e.g. 401 → "invalid token").
+ */
+export class AexolMcpError extends Error {
+    status;
+    code;
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = "AexolMcpError";
+        this.status = opts.status;
+        this.code = opts.code;
+    }
+}
+export class AexolMcpClient {
+    apiUrl;
+    apiKey;
+    timeoutMs;
+    constructor(apiUrl, apiKey, timeoutMs = 30_000) {
+        this.apiUrl = apiUrl;
+        this.apiKey = apiKey;
+        this.timeoutMs = timeoutMs;
+    }
+    /** Low-level: send a JSON-RPC call and return its `result` field. */
+    async call(method, params) {
+        const body = JSON.stringify({
+            jsonrpc: "2.0",
+            // crypto.randomUUID is overkill; a counter would do, but this keeps the
+            // module stateless. JSON-RPC ids only need to be unique per outstanding call.
+            id: Math.floor(Math.random() * Number.MAX_SAFE_INTEGER),
+            method,
+            params,
+        });
+        let res;
+        try {
+            res = await fetch(this.apiUrl, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                body,
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new AexolMcpError(`Network error talking to ${this.apiUrl}: ${msg}`);
+        }
+        if (!res.ok) {
+            // Try to read a body for context, but don't fail if we can't.
+            let detail = "";
+            try {
+                detail = (await res.text()).slice(0, 500);
+            }
+            catch {
+                /* ignore */
+            }
+            throw new AexolMcpError(`HTTP ${res.status} ${res.statusText} from ${this.apiUrl}${detail ? `: ${detail}` : ""}`, { status: res.status });
+        }
+        let payload;
+        try {
+            payload = (await res.json());
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new AexolMcpError(`Invalid JSON response from ${this.apiUrl}: ${msg}`);
+        }
+        if ("error" in payload && payload.error) {
+            throw new AexolMcpError(`JSON-RPC error ${payload.error.code}: ${payload.error.message}`, { code: payload.error.code });
+        }
+        if (!("result" in payload)) {
+            throw new AexolMcpError(`JSON-RPC response missing 'result' field`);
+        }
+        return payload.result;
+    }
+    /**
+     * Fetch the tool catalog. The Aexol backend returns `{ tools: [...] }`
+     * per JSON-RPC convention, but we accept the raw array shape too in case
+     * the server format drifts.
+     */
+    async listTools() {
+        const result = await this.call("tools/list");
+        if (Array.isArray(result))
+            return result;
+        if (result && Array.isArray(result.tools))
+            return result.tools;
+        throw new AexolMcpError("tools/list returned an unexpected payload shape");
+    }
+    /**
+     * Invoke a single tool. Returns the raw `{ content, isError? }` envelope —
+     * the caller (the pi extension) decides how to surface it back to the model.
+     */
+    async callTool(name, args) {
+        const result = await this.call("tools/call", {
+            name,
+            arguments: args ?? {},
+        });
+        if (!result || typeof result !== "object" || !Array.isArray(result.content)) {
+            throw new AexolMcpError(`tools/call returned an unexpected payload for "${name}"`);
+        }
+        return result;
+    }
+}

package/dist/preflight.js

@@ -0,0 +1,36 @@
+/**
+ * Shared pre-flight check: every authenticated `spectral` subcommand (and the
+ * fall-through to pi) must verify that credentials exist in
+ * `~/.spectral/config.json` before proceeding.
+ *
+ * Extracted from `cli.ts` so `serve` (and any future subcommand) reuses the
+ * exact same UX — message wording, exit code, stderr formatting.
+ *
+ * `requireLogin()` writes to stderr and calls `process.exit(1)` on failure;
+ * `checkLogin()` is the testable variant that just reports the result so we
+ * can assert on it without killing the test runner.
+ */
+import { getConfigFile, readConfig } from "./config.js";
+// Plain ANSI red. Mirrors the helper in cli.ts; we intentionally keep this
+// dependency-light so pre-flight stays cheap on cold start.
+function red(s) {
+    return process.stdout.isTTY || process.stderr.isTTY ? `\x1b[31m${s}\x1b[0m` : s;
+}
+/** Inspect login state without side effects. Safe to call from tests. */
+export async function checkLogin() {
+    const cfg = await readConfig();
+    return { ok: cfg !== null, config: cfg, configFile: getConfigFile() };
+}
+/**
+ * Enforce login: returns the config on success, prints a friendly error and
+ * exits 1 on failure. Matches the wording used by the main spawn path.
+ */
+export async function requireLogin() {
+    const result = await checkLogin();
+    if (!result.ok || !result.config) {
+        process.stderr.write(red(`✗ Not logged in. Run: spectral login\n`));
+        process.stderr.write(`  (expected credentials at ${result.configFile})\n`);
+        process.exit(1);
+    }
+    return result.config;
+}

package/dist/relay/client.js

@@ -0,0 +1,240 @@
+/**
+ * RelayClient — long-lived WebSocket connection to the Aexol backend's
+ * `/agent-connection` endpoint.
+ *
+ * Responsibilities (Batch 2):
+ *  - Open and maintain a single WS to the relay, authenticated with the
+ *    machine JWT via `Authorization: Bearer <jwt>`.
+ *  - Reply `{kind:"pong"}` to backend `{kind:"ping"}`. Backend closes
+ *    `4408 heartbeat-timeout` if it doesn't hear from us within 90s; we
+ *    rely on the backend pings rather than emitting our own (single source
+ *    of liveness, no jitter on our side).
+ *  - On unexpected close, reconnect forever with exponential backoff +
+ *    ±20% jitter, capped at 30s. There is no "give up" state — if the
+ *    machine is offline for hours, we just keep trying. Operators can
+ *    `Ctrl-C` to stop.
+ *  - Buffer outbound frames in a small queue while the socket is closed.
+ *    Capped at 100 frames; oldest is dropped on overflow. Until Batch 3
+ *    introduces relay envelopes there's nothing meaningful to send anyway,
+ *    so this is mostly future-proofing.
+ *
+ * Out of scope for Batch 2 (Batch 3 work):
+ *  - Envelope routing (`rest_request` / `subscribe` / `ws_event`). The
+ *    client emits `frame` for every non-pong frame; the dispatcher in
+ *    `serve.ts` (currently just an ack/echo) will own translation.
+ *
+ * Events (typed via `RelayClientEvents`):
+ *  - `open`            - connected and welcomed
+ *  - `welcome`         - backend `{kind:"welcome"}` frame
+ *  - `frame`           - any non-pong, non-welcome frame
+ *  - `close`           - socket closed (we may reconnect after)
+ *  - `error`           - non-fatal error (parse failure, send failure)
+ *  - `reconnect-scheduled` - emitted with the delay in ms before each retry
+ *
+ * Threading model: `node:events` is single-threaded; all callbacks fire on
+ * the same event loop turn. Listeners must be cheap.
+ */
+import { EventEmitter } from "node:events";
+import WebSocket from "ws";
+/** Maximum outbound queue size while disconnected. */
+const SEND_QUEUE_CAP = 100;
+/** Backoff schedule (ms). The last value is the cap and is reused indefinitely. */
+const RECONNECT_SCHEDULE = [1000, 2000, 5000, 15000, 30000];
+/** ±20% jitter on each scheduled delay. */
+const JITTER_RATIO = 0.2;
+export class RelayClient extends EventEmitter {
+    relayUrl;
+    machineJwt;
+    WS;
+    logger;
+    exit;
+    ws = null;
+    disposed = false;
+    reconnectAttempt = 0;
+    reconnectTimer = null;
+    sendQueue = [];
+    constructor(opts) {
+        super();
+        this.relayUrl = opts.relayUrl;
+        this.machineJwt = opts.machineJwt;
+        this.WS = opts.webSocketImpl ?? WebSocket;
+        this.logger = opts.logger ?? console;
+        this.exit = opts.exit ?? ((code) => process.exit(code));
+    }
+    /** Open the connection. Idempotent — calling twice is a no-op. */
+    connect() {
+        if (this.disposed)
+            return;
+        if (this.ws)
+            return;
+        this.openSocket();
+    }
+    /**
+     * Send a frame. If the socket is open it goes immediately; otherwise
+     * it's queued (capped at 100 — oldest dropped) and flushed on the next
+     * successful `open`.
+     *
+     * Returns `true` if the frame was sent or queued, `false` if it was
+     * dropped due to dispose.
+     */
+    send(frame) {
+        if (this.disposed)
+            return false;
+        const wire = typeof frame === "string" ? frame : JSON.stringify(frame);
+        const ws = this.ws;
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            try {
+                ws.send(wire);
+                return true;
+            }
+            catch (err) {
+                this.emit("error", err);
+                return false;
+            }
+        }
+        // Queue it.
+        if (this.sendQueue.length >= SEND_QUEUE_CAP) {
+            this.sendQueue.shift();
+        }
+        this.sendQueue.push(wire);
+        return true;
+    }
+    /**
+     * Close the connection and stop reconnecting. After dispose, this client
+     * is dead — create a new one to reconnect.
+     */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        const ws = this.ws;
+        this.ws = null;
+        if (ws) {
+            try {
+                ws.close(1000, "client disposed");
+            }
+            catch {
+                // ignore — best-effort
+            }
+        }
+        this.sendQueue = [];
+    }
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    openSocket() {
+        const ws = new this.WS(this.relayUrl, {
+            headers: { Authorization: `Bearer ${this.machineJwt}` },
+        });
+        this.ws = ws;
+        ws.on("open", () => {
+            this.reconnectAttempt = 0;
+            // Flush any queued frames.
+            const queued = this.sendQueue;
+            this.sendQueue = [];
+            for (const wire of queued) {
+                try {
+                    ws.send(wire);
+                }
+                catch (err) {
+                    // Re-queue on failure and stop draining; the next open will retry.
+                    this.sendQueue = queued.slice(queued.indexOf(wire));
+                    this.emit("error", err);
+                    return;
+                }
+            }
+            this.emit("open");
+        });
+        ws.on("message", (data) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(data.toString());
+            }
+            catch (err) {
+                this.emit("error", err);
+                return;
+            }
+            // Heartbeat: reply pong inline, do NOT propagate.
+            if (parsed && parsed.kind === "ping") {
+                try {
+                    ws.send(JSON.stringify({ kind: "pong" }));
+                }
+                catch (err) {
+                    this.emit("error", err);
+                }
+                return;
+            }
+            if (parsed && parsed.kind === "welcome") {
+                this.emit("welcome", parsed);
+                return;
+            }
+            this.emit("frame", parsed);
+        });
+        ws.on("error", (err) => {
+            // `ws` emits 'error' before 'close'; we don't reconnect here — the
+            // 'close' handler is the single reconnect entry point so we don't
+            // double-schedule.
+            this.emit("error", err);
+        });
+        ws.on("close", (code, reason) => {
+            this.ws = null;
+            const reasonStr = reason?.toString() ?? "";
+            this.emit("close", { code, reason: reasonStr });
+            if (this.disposed)
+                return;
+            // Backend evicts older WS sessions when a newer registration arrives
+            // for the same machineId (see backend `registry.ts: register()`).
+            // If we reconnect here we'll just kick out the new instance, which
+            // will then reconnect and kick us out — an infinite ping-pong.
+            // Exit instead so the operator (or process supervisor) notices.
+            if (code === 1000 && reasonStr === "replaced-by-newer-registration") {
+                this.logger.error("\n✗ Another `spectral serve` instance has registered for this machine.");
+                this.logger.error("  This instance is exiting to avoid a reconnect loop.");
+                this.logger.error("  If you want to run multiple instances, use distinct `--machine-name` values.\n");
+                this.dispose();
+                this.exit(1);
+                return;
+            }
+            this.scheduleReconnect();
+        });
+    }
+    scheduleReconnect() {
+        if (this.disposed)
+            return;
+        if (this.reconnectTimer)
+            return;
+        const idx = Math.min(this.reconnectAttempt, RECONNECT_SCHEDULE.length - 1);
+        const base = RECONNECT_SCHEDULE[idx];
+        const jitter = base * JITTER_RATIO * (Math.random() * 2 - 1);
+        const delay = Math.max(0, Math.round(base + jitter));
+        this.reconnectAttempt++;
+        this.emit("reconnect-scheduled", { delayMs: delay, attempt: this.reconnectAttempt });
+        // IMPORTANT: do NOT `unref()` this timer. `spectral serve` is a long-
+        // lived daemon and the reconnect timer is frequently the ONLY thing
+        // keeping the event loop alive between a WS close and the next open
+        // (the SessionStreamManager holds nothing while idle). An unref'd
+        // timer lets Node decide the loop is empty and exit the process,
+        // which manifests as the daemon silently dying after a network blip.
+        // Tests dispose the client explicitly via `dispose()`, which clears
+        // this timer, so they still terminate cleanly.
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (this.disposed)
+                return;
+            try {
+                this.openSocket();
+            }
+            catch (err) {
+                // A synchronous throw from the WebSocket constructor (DNS, bad
+                // URL, etc.) must not kill the daemon — log it and re-schedule
+                // so the backoff continues forever.
+                this.emit("error", err);
+                this.scheduleReconnect();
+            }
+        }, delay);
+    }
+}