llm-cli-gateway 2.2.0 → 2.4.0

package/dist/validation-tools.js

@@ -57,6 +57,12 @@ export function registerValidationTools(server, deps) {
         judgeModel: providerSchema
             .optional()
             .describe("Optional provider to run an explicit judge synthesis job."),
+    }, {
+        title: "Multi-model validation",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ question, models, focus, judgeModel }) => textResponse({
         success: true,
         tool: "validate_with_models",
@@ -73,6 +79,12 @@ export function registerValidationTools(server, deps) {
         answer: z.string().min(1).describe("Answer to review."),
         question: z.string().optional().describe("Original question, if available."),
         model: providerSchema.default("codex").describe("Provider to ask for the second opinion."),
+    }, {
+        title: "Second opinion",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ answer, question, model }) => textResponse({
         success: true,
         tool: "second_opinion",
@@ -87,6 +99,12 @@ export function registerValidationTools(server, deps) {
     server.tool("compare_answers", "Summarize agreement/differences between caller-provided answers LOCALLY — does not call any provider.", {
         question: z.string().min(1).describe("Question the answers respond to."),
         answers: z.array(z.string().min(1)).min(2).describe("Two or more answers to compare."),
+    }, {
+        title: "Compare answers (local)",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ question, answers }) => textResponse({
         success: true,
         tool: "compare_answers",
@@ -106,6 +124,12 @@ export function registerValidationTools(server, deps) {
             .default("normal")
             .describe("How aggressively to review."),
         models: providerListSchema.describe("Providers to ask for adversarial review."),
+    }, {
+        title: "Red-team review",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ content, riskLevel, models }) => textResponse({
         success: true,
         tool: "red_team_review",
@@ -120,6 +144,12 @@ export function registerValidationTools(server, deps) {
     server.tool("consensus_check", "Ask provider CLIs whether they agree or disagree with a claim (starts validation jobs).", {
         claim: z.string().min(1).describe("Claim to check across providers."),
         models: providerListSchema.describe("Providers to ask for agreement or disagreement."),
+    }, {
+        title: "Consensus check",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ claim, models }) => textResponse({
         success: true,
         tool: "consensus_check",
@@ -133,6 +163,12 @@ export function registerValidationTools(server, deps) {
     server.tool("ask_model", "Ask one provider CLI a question through the simplified validation surface (starts a validation job).", {
         question: z.string().min(1).describe("Question for one provider."),
         model: providerSchema.default("claude").describe("Provider to ask."),
+    }, {
+        title: "Ask one model",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ question, model }) => textResponse({
         success: true,
         tool: "ask_model",
@@ -150,6 +186,12 @@ export function registerValidationTools(server, deps) {
             .min(1)
             .describe("Terminal normalized provider results from job_result."),
         judgeModel: providerSchema.default("codex").describe("Provider to run the judge synthesis."),
+    }, {
+        title: "Synthesize validation",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
     }, async ({ question, providerResults, judgeModel }) => textResponse({
         success: true,
         tool: "synthesize_validation",
@@ -160,9 +202,21 @@ export function registerValidationTools(server, deps) {
             judgeProvider: judgeModel,
         }),
     }));
-    server.tool("list_available_models", "List models and capabilities for every available provider CLI (takes no arguments; complements per-provider list_models).", {}, async () => textResponse({ success: true, models: getAvailableCliInfo() }));
+    server.tool("list_available_models", "List models and capabilities for every available provider CLI (takes no arguments; complements per-provider list_models).", {}, {
+        title: "All provider models",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async () => textResponse({ success: true, models: getAvailableCliInfo() }));
     server.tool("job_status", "Check a VALIDATION job's status (jobs started by validate_with_models/ask_model/etc.) — distinct from llm_job_status, which tracks provider request jobs.", {
         jobId: z.string().min(1).describe("Validation job ID."),
+    }, {
+        title: "Validation job status",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ jobId }) => {
         const job = deps.asyncJobManager.getJobSnapshot(jobId);
         if (!job) {
@@ -182,6 +236,12 @@ export function registerValidationTools(server, deps) {
             .max(2000000)
             .default(200000)
             .describe("Maximum result size."),
+    }, {
+        title: "Validation job result",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ jobId, provider, maxChars }) => {
         const result = deps.asyncJobManager.getJobResult(jobId, maxChars);
         if (!result) {

package/dist/xai-api-provider.d.ts

@@ -0,0 +1,43 @@
+import type { Logger } from "./logger.js";
+export type XaiResponsesRole = "system" | "user" | "assistant";
+export type XaiReasoningEffort = "none" | "low" | "medium" | "high";
+export interface XaiResponsesInputMessage {
+    role: XaiResponsesRole;
+    content: string;
+}
+export interface XaiResponsesRequest {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    input: string | XaiResponsesInputMessage[];
+    instructions?: string;
+    previousResponseId?: string;
+    maxOutputTokens?: number;
+    temperature?: number;
+    topP?: number;
+    reasoningEffort?: XaiReasoningEffort;
+    timeoutMs?: number;
+}
+export interface XaiResponsesUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    costUsd?: number;
+    raw?: unknown;
+}
+export interface XaiResponsesResult {
+    responseId: string | null;
+    model: string;
+    status: string | null;
+    text: string;
+    usage: XaiResponsesUsage;
+    raw: unknown;
+    httpStatus: number;
+}
+export declare class XaiApiError extends Error {
+    readonly status: number | null;
+    readonly responseText: string;
+    readonly code?: string | undefined;
+    constructor(message: string, status?: number | null, responseText?: string, code?: string | undefined);
+}
+export declare function createXaiResponse(params: XaiResponsesRequest, logger?: Logger): Promise<XaiResponsesResult>;

package/dist/xai-api-provider.js

@@ -0,0 +1,191 @@
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { URL } from "node:url";
+import { createCircuitBreaker, withRetry } from "./retry.js";
+import { logWarn, noopLogger } from "./logger.js";
+const MAX_RESPONSE_BYTES = 50 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 600_000;
+export class XaiApiError extends Error {
+    status;
+    responseText;
+    code;
+    constructor(message, status = null, responseText = "", code) {
+        super(message);
+        this.status = status;
+        this.responseText = responseText;
+        this.code = code;
+        this.name = "XaiApiError";
+    }
+}
+let xaiCircuitBreaker = null;
+function getXaiCircuitBreaker(logger) {
+    xaiCircuitBreaker ??= createCircuitBreaker({
+        failureThreshold: 3,
+        resetTimeout: 60_000,
+        onStateChange: state => logWarn(logger, `[xai-api] circuit breaker state changed to ${state}`),
+    });
+    return xaiCircuitBreaker;
+}
+function isHttpTransient(error) {
+    const status = typeof error?.status === "number" ? error.status : null;
+    if (status === 429 || (status !== null && status >= 500))
+        return true;
+    return ["ECONNRESET", "ETIMEDOUT", "ECONNREFUSED", "EPIPE"].includes(String(error?.code ?? ""));
+}
+function responsesUrl(baseUrl) {
+    const trimmed = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${trimmed}/responses`);
+    if (url.protocol !== "https:" &&
+        !(url.protocol === "http:" && ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname))) {
+        throw new XaiApiError("xAI API baseUrl must use https unless it targets localhost/loopback");
+    }
+    return url;
+}
+function extractErrorMessage(status, body) {
+    if (!body)
+        return `xAI API request failed with HTTP ${status}`;
+    try {
+        const parsed = JSON.parse(body);
+        const message = parsed?.error?.message ?? parsed?.message ?? parsed?.error;
+        if (typeof message === "string" && message.length > 0) {
+            return `xAI API request failed with HTTP ${status}: ${message}`;
+        }
+    }
+    catch {
+    }
+    return `xAI API request failed with HTTP ${status}: ${body.slice(0, 1000)}`;
+}
+function normalizeCostUsd(usage) {
+    const ticks = usage?.cost_in_usd_ticks;
+    if (typeof ticks === "number" && Number.isFinite(ticks))
+        return ticks / 10_000_000_000;
+    const nanos = usage?.cost_in_nano_usd;
+    if (typeof nanos === "number" && Number.isFinite(nanos))
+        return nanos / 1_000_000_000;
+    return undefined;
+}
+function extractResponseText(parsed) {
+    const output = Array.isArray(parsed?.output) ? parsed.output : [];
+    const chunks = [];
+    for (const item of output) {
+        if (item?.type !== "message" || !Array.isArray(item.content))
+            continue;
+        for (const content of item.content) {
+            if ((content?.type === "output_text" || content?.type === "text") &&
+                typeof content.text === "string") {
+                chunks.push(content.text);
+            }
+        }
+    }
+    if (chunks.length > 0)
+        return chunks.join("");
+    if (typeof parsed?.output_text === "string")
+        return parsed.output_text;
+    return "";
+}
+function parseResponsesResult(status, body) {
+    const parsed = JSON.parse(body);
+    const usage = parsed?.usage ?? {};
+    return {
+        responseId: typeof parsed?.id === "string" ? parsed.id : null,
+        model: typeof parsed?.model === "string" ? parsed.model : "unknown",
+        status: typeof parsed?.status === "string" ? parsed.status : null,
+        text: extractResponseText(parsed),
+        usage: {
+            inputTokens: typeof usage.input_tokens === "number"
+                ? usage.input_tokens
+                : typeof usage.prompt_tokens === "number"
+                    ? usage.prompt_tokens
+                    : undefined,
+            outputTokens: typeof usage.output_tokens === "number"
+                ? usage.output_tokens
+                : typeof usage.completion_tokens === "number"
+                    ? usage.completion_tokens
+                    : undefined,
+            cacheReadTokens: typeof usage?.input_tokens_details?.cached_tokens === "number"
+                ? usage.input_tokens_details.cached_tokens
+                : typeof usage?.prompt_tokens_details?.cached_tokens === "number"
+                    ? usage.prompt_tokens_details.cached_tokens
+                    : undefined,
+            costUsd: normalizeCostUsd(usage),
+            raw: usage,
+        },
+        raw: parsed,
+        httpStatus: status,
+    };
+}
+function postJson(url, body, apiKey, timeoutMs) {
+    const payload = JSON.stringify(body);
+    const requester = url.protocol === "https:" ? httpsRequest : httpRequest;
+    return new Promise((resolve, reject) => {
+        const req = requester(url, {
+            method: "POST",
+            timeout: timeoutMs,
+            headers: {
+                authorization: `Bearer ${apiKey}`,
+                "content-type": "application/json",
+                accept: "application/json",
+                "content-length": Buffer.byteLength(payload),
+            },
+        }, res => {
+            const chunks = [];
+            let bytes = 0;
+            res.on("data", chunk => {
+                const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                bytes += buf.length;
+                if (bytes > MAX_RESPONSE_BYTES) {
+                    req.destroy(new XaiApiError("xAI API response exceeded the 50MB limit", null));
+                    return;
+                }
+                chunks.push(buf);
+            });
+            res.on("end", () => {
+                const text = Buffer.concat(chunks).toString("utf8");
+                const status = res.statusCode ?? 0;
+                if (status < 200 || status >= 300) {
+                    const err = new XaiApiError(extractErrorMessage(status, text), status, text);
+                    reject(err);
+                    return;
+                }
+                resolve(text);
+            });
+        });
+        req.on("timeout", () => {
+            req.destroy(new XaiApiError("xAI API request timed out", null, "", "ETIMEDOUT"));
+        });
+        req.on("error", reject);
+        req.end(payload);
+    });
+}
+export async function createXaiResponse(params, logger = noopLogger) {
+    const requestBody = {
+        model: params.model,
+        input: params.input,
+        store: true,
+    };
+    if (params.instructions)
+        requestBody.instructions = params.instructions;
+    if (params.previousResponseId)
+        requestBody.previous_response_id = params.previousResponseId;
+    if (params.maxOutputTokens !== undefined)
+        requestBody.max_output_tokens = params.maxOutputTokens;
+    if (params.temperature !== undefined)
+        requestBody.temperature = params.temperature;
+    if (params.topP !== undefined)
+        requestBody.top_p = params.topP;
+    if (params.reasoningEffort !== undefined) {
+        requestBody.reasoning = { effort: params.reasoningEffort };
+    }
+    const url = responsesUrl(params.baseUrl);
+    const timeoutMs = params.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const body = await withRetry(() => postJson(url, requestBody, params.apiKey, timeoutMs), getXaiCircuitBreaker(logger), {
+        initialDelay: 1_000,
+        maxDelay: 30_000,
+        factor: 2,
+        isTransient: isHttpTransient,
+        onRetry: (error, attempt, delay) => {
+            logWarn(logger, `[xai-api] transient request failure on attempt ${attempt}; retrying in ${delay}ms: ${error.message}`);
+        },
+    }, logger);
+    return parseResponsesResult(200, body);
+}

package/migrations/001_initial_schema.sql

@@ -0,0 +1,65 @@
+-- Initial schema for llm-cli-gateway PostgreSQL backend
+-- Sessions and active session management
+
+-- Create sessions table
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY,
+  cli VARCHAR(32) NOT NULL CHECK (cli IN ('claude', 'codex', 'gemini', 'grok', 'mistral', 'grok-api')),
+  description TEXT,
+  metadata JSONB DEFAULT '{}'::JSONB,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  last_used_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Create active_sessions table (enforces one active per CLI)
+CREATE TABLE IF NOT EXISTS active_sessions (
+  cli VARCHAR(32) PRIMARY KEY CHECK (cli IN ('claude', 'codex', 'gemini', 'grok', 'mistral', 'grok-api')),
+  session_id TEXT REFERENCES sessions(id) ON DELETE CASCADE,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Indexes for performance
+CREATE INDEX IF NOT EXISTS idx_sessions_cli ON sessions(cli);
+CREATE INDEX IF NOT EXISTS idx_sessions_last_used_at ON sessions(last_used_at DESC);
+CREATE INDEX IF NOT EXISTS idx_sessions_metadata ON sessions USING GIN(metadata);
+CREATE INDEX IF NOT EXISTS idx_sessions_cli_last_used ON sessions(cli, last_used_at DESC);
+
+-- View for session summary (joins sessions + active_sessions)
+CREATE OR REPLACE VIEW session_summary AS
+SELECT
+  s.id,
+  s.cli,
+  s.description,
+  s.created_at,
+  s.last_used_at,
+  (a.session_id IS NOT NULL) AS is_active
+FROM sessions s
+LEFT JOIN active_sessions a ON s.id = a.session_id;
+
+-- Cleanup function for expired sessions
+CREATE OR REPLACE FUNCTION cleanup_expired_sessions(max_age_days INTEGER DEFAULT 30)
+RETURNS INTEGER AS $$
+DECLARE
+  deleted_count INTEGER;
+BEGIN
+  -- Delete sessions older than max_age_days that are not active
+  DELETE FROM sessions
+  WHERE last_used_at < NOW() - INTERVAL '1 day' * max_age_days
+    AND id NOT IN (SELECT session_id FROM active_sessions WHERE session_id IS NOT NULL);
+
+  GET DIAGNOSTICS deleted_count = ROW_COUNT;
+  RETURN deleted_count;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Schema migrations tracking table
+CREATE TABLE IF NOT EXISTS schema_migrations (
+  version INTEGER PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Record this migration
+INSERT INTO schema_migrations (version, name)
+VALUES (1, '001_initial_schema')
+ON CONFLICT (version) DO NOTHING;

package/migrations/002_session_ids_as_text.sql

@@ -0,0 +1,26 @@
+-- Convert session identifiers from UUID to opaque string IDs (TEXT)
+-- Keeps compatibility with file-based manager and legacy custom IDs.
+
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1
+    FROM information_schema.columns
+    WHERE table_schema = 'public'
+      AND table_name = 'sessions'
+      AND column_name = 'id'
+      AND udt_name = 'uuid'
+  ) THEN
+    ALTER TABLE active_sessions DROP CONSTRAINT IF EXISTS active_sessions_session_id_fkey;
+    ALTER TABLE sessions ALTER COLUMN id TYPE TEXT USING id::text;
+    ALTER TABLE active_sessions ALTER COLUMN session_id TYPE TEXT USING session_id::text;
+    ALTER TABLE active_sessions
+      ADD CONSTRAINT active_sessions_session_id_fkey
+      FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE;
+  END IF;
+END;
+$$ LANGUAGE plpgsql;
+
+INSERT INTO schema_migrations (version, name)
+VALUES (2, '002_session_ids_as_text')
+ON CONFLICT (version) DO NOTHING;

package/migrations/003_provider_type_sessions.sql

@@ -0,0 +1,20 @@
+-- Widen session provider constraints for API-backed providers.
+-- Existing PostgreSQL installations created before the Grok API provider split
+-- only accepted the original CLI subset. Keep the column values opaque strings
+-- but enforce the current provider set.
+
+ALTER TABLE sessions DROP CONSTRAINT IF EXISTS sessions_cli_check;
+ALTER TABLE sessions ALTER COLUMN cli TYPE VARCHAR(32);
+ALTER TABLE sessions
+  ADD CONSTRAINT sessions_cli_check
+  CHECK (cli IN ('claude', 'codex', 'gemini', 'grok', 'mistral', 'grok-api'));
+
+ALTER TABLE active_sessions DROP CONSTRAINT IF EXISTS active_sessions_cli_check;
+ALTER TABLE active_sessions ALTER COLUMN cli TYPE VARCHAR(32);
+ALTER TABLE active_sessions
+  ADD CONSTRAINT active_sessions_cli_check
+  CHECK (cli IN ('claude', 'codex', 'gemini', 'grok', 'mistral', 'grok-api'));
+
+INSERT INTO schema_migrations (version, name)
+VALUES (3, '003_provider_type_sessions')
+ON CONFLICT (version) DO NOTHING;

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "llm-cli-gateway",
-  "version": "2.0.0",
+  "version": "2.4.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "llm-cli-gateway",
-      "version": "2.0.0",
+      "version": "2.4.0",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.29.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-cli-gateway",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "mcpName": "io.github.verivus-oss/llm-cli-gateway",
   "description": "MCP server providing unified access to Claude Code, Codex, Gemini, Grok, and Mistral Vibe CLIs with session management, retry logic, async job orchestration, durable job results, and cross-LLM validation.",
   "license": "MIT",
@@ -46,6 +46,7 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "!dist/__tests__/**",
+    "migrations/**/*.sql",
     "npm-shrinkwrap.json",
     "setup/status.schema.json",
     "README.md",