llm-cli-gateway 2.11.0 → 2.12.0

package/dist/validation-receipt.d.ts

@@ -0,0 +1,68 @@
+import type { AsyncJobManager } from "./async-job-manager.js";
+import type { ValidationRunRecord, ValidationRunStore } from "./job-store.js";
+import { type ValidationReport } from "./validation-report.js";
+export declare const VALIDATION_RECEIPT_SCHEMA_VERSION = "validation-receipt.v1";
+export interface ReceiptDeps {
+    asyncJobManager: AsyncJobManager;
+    validationRunStore?: ValidationRunStore | null;
+}
+export type ValidationReportV1Content = ValidationReport["structuredContent"];
+export interface ValidationReceipt {
+    schemaVersion: string;
+    validationId: string;
+    ownerPrincipal: string;
+    mintedAt: string;
+    intent: string;
+    models: string[];
+    report: ValidationReportV1Content;
+    humanReadable: string;
+    canonicalSha256: string;
+    prevSha256?: string | null;
+    seq?: number | null;
+    signature?: string | null;
+}
+export interface ValidationRunState {
+    validationId: string;
+    status: ValidationRunRecord["status"];
+    providers: Array<{
+        provider: string;
+        jobId: string;
+        status: string;
+    }>;
+    judge: {
+        provider: string;
+        jobId: string;
+        status: string;
+    } | null;
+}
+export interface RawResponse {
+    provider: string;
+    jobId: string;
+    text: string;
+}
+export type ValidationReceiptResult = {
+    status: "minted";
+    validationId: string;
+    receipt: ValidationReceipt;
+    mintedAt: string;
+    rawResponses?: RawResponse[];
+} | {
+    status: "pending";
+    validationId: string;
+    run: ValidationRunState;
+} | {
+    status: "expired_unminted";
+    validationId: string;
+} | {
+    status: "not_found";
+    validationId: string;
+};
+export declare function canonicalJson(value: unknown): string;
+export declare function computeCanonicalSha256(structuredContent: ValidationReportV1Content): string;
+export declare function resolveValidationReceipt(deps: ReceiptDeps, validationId: string, opts: {
+    caller: string;
+    includeRawResponses?: boolean;
+}): ValidationReceiptResult;
+export declare function eagerMintFromValidationId(deps: ReceiptDeps, validationId: string): void;
+export declare function eagerMintFromJobId(deps: ReceiptDeps, jobId: string): void;
+export declare function currentCaller(): string;

package/dist/validation-receipt.js

@@ -0,0 +1,245 @@
+import { createHash } from "node:crypto";
+import { normalizeJobResult, normalizeSkippedProvider } from "./validation-normalizer.js";
+import { buildValidationReport, deriveValidationRunStatus, renderHumanReport, } from "./validation-report.js";
+import { getRequestContext, principalCanAccess, resolveOwnerPrincipal } from "./request-context.js";
+export const VALIDATION_RECEIPT_SCHEMA_VERSION = "validation-receipt.v1";
+const TERMINAL_JOB_STATUSES = new Set(["completed", "failed", "canceled", "orphaned"]);
+export function canonicalJson(value) {
+    return JSON.stringify(sortDeep(value));
+}
+function sortDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortDeep);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = sortDeep(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+export function computeCanonicalSha256(structuredContent) {
+    return createHash("sha256").update(canonicalJson(structuredContent), "utf8").digest("hex");
+}
+function isTerminal(status) {
+    return TERMINAL_JOB_STATUSES.has(status);
+}
+function parseRequest(requestJson) {
+    try {
+        const parsed = JSON.parse(requestJson);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function tryMint(deps, run) {
+    const store = deps.validationRunStore;
+    if (!store)
+        return { kind: "pending" };
+    const providerResults = [];
+    for (const link of run.providerLinks) {
+        const jobResult = deps.asyncJobManager.getJobResult(link.jobId);
+        if (!jobResult)
+            return { kind: "evicted" };
+        if (!isTerminal(jobResult.status))
+            return { kind: "pending" };
+        providerResults.push({ link, result: normalizeJobResult(link.provider, null, jobResult) });
+    }
+    let judgeStatus = null;
+    if (run.judgeLink) {
+        const judgeResult = deps.asyncJobManager.getJobResult(run.judgeLink.jobId);
+        if (!judgeResult)
+            return { kind: "evicted" };
+        if (!isTerminal(judgeResult.status))
+            return { kind: "pending" };
+        judgeStatus = judgeResult.status;
+    }
+    const request = parseRequest(run.requestJson);
+    const requested = Array.isArray(request.modelList) ? request.modelList : [];
+    const dispatched = new Set(run.providerLinks.map(link => link.provider));
+    const results = providerResults.map(entry => entry.result);
+    for (const provider of requested) {
+        if (!dispatched.has(provider)) {
+            results.push(normalizeSkippedProvider(provider, "Provider was not dispatched for this run."));
+        }
+    }
+    const judgeCompleted = judgeStatus === "completed";
+    const synthesis = run.judgeLink
+        ? {
+            status: judgeCompleted ? "completed" : "skipped",
+            judgeModel: run.judgeLink.provider,
+            rawJobReference: {
+                jobId: run.judgeLink.jobId,
+                correlationId: run.judgeLink.correlationId,
+                statusTool: "job_status",
+                resultTool: "job_result",
+            },
+            note: judgeCompleted
+                ? "Judge synthesis completed."
+                : `Judge job ended in '${judgeStatus}' without a synthesis result.`,
+        }
+        : {
+            status: "not_requested",
+            judgeModel: null,
+            rawJobReference: null,
+            note: "No judge synthesis was requested.",
+        };
+    const modelList = (requested.length > 0 ? requested : Array.from(dispatched));
+    const report = buildValidationReport({
+        validationId: run.validationId,
+        status: deriveValidationRunStatus(results, synthesis.status),
+        startedAt: run.createdAt,
+        intent: run.intent,
+        originalRequest: {
+            question: request.question,
+            content: request.content,
+            focus: request.focus,
+        },
+        modelList,
+        results,
+        synthesis,
+    });
+    const structuredContent = report.structuredContent;
+    const record = {
+        validationId: run.validationId,
+        ownerPrincipal: run.ownerPrincipal,
+        mintedAt: new Date().toISOString(),
+        schemaVersion: VALIDATION_RECEIPT_SCHEMA_VERSION,
+        reportJson: JSON.stringify(structuredContent),
+        canonicalSha256: computeCanonicalSha256(structuredContent),
+        prevSha256: null,
+        seq: null,
+        signature: null,
+        models: structuredContent.modelList,
+        hasMaterialDisagreement: structuredContent.disagreements.hasMaterialDisagreement,
+        confidence: structuredContent.confidence,
+    };
+    store.recordValidationReceipt(record);
+    store.setValidationRunStatus(run.validationId, "finalized");
+    const stored = store.getValidationReceipt(run.validationId);
+    return { kind: "minted", record: stored ?? record };
+}
+function receiptEnvelope(record) {
+    const report = JSON.parse(record.reportJson);
+    return {
+        schemaVersion: record.schemaVersion,
+        validationId: record.validationId,
+        ownerPrincipal: record.ownerPrincipal,
+        mintedAt: record.mintedAt,
+        intent: report.intent,
+        models: record.models,
+        report,
+        humanReadable: renderHumanReport(report),
+        canonicalSha256: record.canonicalSha256,
+        prevSha256: record.prevSha256,
+        seq: record.seq,
+        signature: record.signature,
+    };
+}
+function collectRawResponses(deps, receipt, caller) {
+    const out = [];
+    const refs = [];
+    for (const output of receipt.report.perModelOutputs) {
+        if (output.jobId)
+            refs.push({ provider: output.provider, jobId: output.jobId });
+    }
+    const judgeRef = receipt.report.synthesis.rawJobReference;
+    if (judgeRef?.jobId) {
+        refs.push({ provider: receipt.report.synthesis.judgeModel ?? "judge", jobId: judgeRef.jobId });
+    }
+    for (const ref of refs) {
+        if (!principalCanAccess(deps.asyncJobManager.getJobOwner(ref.jobId), caller))
+            continue;
+        const jobResult = deps.asyncJobManager.getJobResult(ref.jobId);
+        if (jobResult)
+            out.push({ provider: ref.provider, jobId: ref.jobId, text: jobResult.stdout });
+    }
+    return out;
+}
+function mintedResult(deps, record, includeRawResponses, caller) {
+    const receipt = receiptEnvelope(record);
+    return {
+        status: "minted",
+        validationId: record.validationId,
+        receipt,
+        mintedAt: record.mintedAt,
+        ...(includeRawResponses ? { rawResponses: collectRawResponses(deps, receipt, caller) } : {}),
+    };
+}
+function runStateOf(deps, run) {
+    const snapStatus = (jobId) => deps.asyncJobManager.getJobSnapshot(jobId)?.status ?? "evicted";
+    return {
+        validationId: run.validationId,
+        status: run.status,
+        providers: run.providerLinks.map(link => ({
+            provider: link.provider,
+            jobId: link.jobId,
+            status: snapStatus(link.jobId),
+        })),
+        judge: run.judgeLink
+            ? {
+                provider: run.judgeLink.provider,
+                jobId: run.judgeLink.jobId,
+                status: snapStatus(run.judgeLink.jobId),
+            }
+            : null,
+    };
+}
+export function resolveValidationReceipt(deps, validationId, opts) {
+    const store = deps.validationRunStore;
+    if (!store)
+        return { status: "not_found", validationId };
+    const existing = store.getValidationReceipt(validationId);
+    if (existing) {
+        if (!principalCanAccess(existing.ownerPrincipal, opts.caller)) {
+            return { status: "not_found", validationId };
+        }
+        return mintedResult(deps, existing, opts.includeRawResponses ?? false, opts.caller);
+    }
+    const run = store.getValidationRun(validationId);
+    if (!run || !principalCanAccess(run.ownerPrincipal, opts.caller)) {
+        return { status: "not_found", validationId };
+    }
+    const outcome = tryMint(deps, run);
+    if (outcome.kind === "minted") {
+        return mintedResult(deps, outcome.record, opts.includeRawResponses ?? false, opts.caller);
+    }
+    if (outcome.kind === "evicted") {
+        return { status: "expired_unminted", validationId };
+    }
+    return { status: "pending", validationId, run: runStateOf(deps, run) };
+}
+export function eagerMintFromValidationId(deps, validationId) {
+    const store = deps.validationRunStore;
+    if (!store)
+        return;
+    try {
+        if (store.getValidationReceipt(validationId))
+            return;
+        const run = store.getValidationRun(validationId);
+        if (!run)
+            return;
+        tryMint(deps, run);
+    }
+    catch {
+    }
+}
+export function eagerMintFromJobId(deps, jobId) {
+    const store = deps.validationRunStore;
+    if (!store)
+        return;
+    let validationId = null;
+    try {
+        validationId = store.getValidationRunIdByJobId(jobId);
+    }
+    catch {
+        return;
+    }
+    if (validationId)
+        eagerMintFromValidationId(deps, validationId);
+}
+export function currentCaller() {
+    return resolveOwnerPrincipal(getRequestContext());
+}

package/dist/validation-report.d.ts

@@ -3,7 +3,7 @@ import type { ValidationIntent } from "./validation-prompts.js";
 export type ValidationReportConfidence = "none" | "low" | "medium" | "high";
 export interface ValidationReportInput {
     validationId: string;
-    status: "running" | "partial" | "not_started";
+    status: "running" | "partial" | "not_started" | "completed";
     startedAt: string;
     intent: ValidationIntent;
     originalRequest: {
@@ -14,7 +14,7 @@ export interface ValidationReportInput {
     modelList: ValidationProvider[];
     results: NormalizedValidationResult[];
     synthesis: {
-        status: "not_requested" | "waiting_for_provider_results" | "running" | "skipped";
+        status: "not_requested" | "waiting_for_provider_results" | "running" | "skipped" | "completed";
         judgeModel: ValidationProvider | null;
         rawJobReference: NormalizedValidationResult["rawJobReference"];
         note: string;
@@ -55,3 +55,5 @@ export interface ValidationReport {
     };
 }
 export declare function buildValidationReport(input: ValidationReportInput): ValidationReport;
+export declare function deriveValidationRunStatus(results: NormalizedValidationResult[], synthesisStatus: ValidationReportInput["synthesis"]["status"]): ValidationReportInput["status"];
+export declare function renderHumanReport(content: ValidationReport["structuredContent"]): string;

package/dist/validation-report.js

@@ -37,6 +37,23 @@ export function buildValidationReport(input) {
         structuredContent,
     };
 }
+export function deriveValidationRunStatus(results, synthesisStatus) {
+    if (results.length === 0)
+        return "not_started";
+    const dispatched = results.filter(result => result.status !== "skipped");
+    if (dispatched.length === 0)
+        return "not_started";
+    const allDispatchedTerminal = dispatched.every(result => result.status === "completed" ||
+        result.status === "failed" ||
+        result.status === "canceled" ||
+        result.status === "orphaned");
+    const hasSkipped = results.some(result => result.status === "skipped");
+    const judgePending = synthesisStatus === "running" || synthesisStatus === "waiting_for_provider_results";
+    if (!allDispatchedTerminal || judgePending) {
+        return hasSkipped ? "partial" : "running";
+    }
+    return "completed";
+}
 function summarizeDisagreement(results) {
     const completed = results.filter(result => result.status === "completed");
     const terminalProblems = results.filter(result => ["failed", "canceled", "orphaned", "skipped"].includes(result.status));
@@ -102,7 +119,7 @@ function recommendationFor(results, hasMaterialDisagreement) {
     }
     return "Completed provider outputs show no normalized verdict disagreement; review rationales and risks before acting.";
 }
-function renderHumanReport(content) {
+export function renderHumanReport(content) {
     const lines = [
         `Validation report ${content.validationId}`,
         `Status: ${content.status}`,

package/dist/validation-tools.js

@@ -2,6 +2,8 @@ import { z } from "zod/v3";
 import { CLI_TYPES } from "./session-manager.js";
 import { getAvailableCliInfo } from "./model-registry.js";
 import { apiProviderCatalogEntry } from "./api-request.js";
+import { getRequestContext, principalCanAccess, resolveOwnerPrincipal } from "./request-context.js";
+import { currentCaller, eagerMintFromJobId, eagerMintFromValidationId, resolveValidationReceipt, } from "./validation-receipt.js";
 import { collectValidationJobResult, startJudgeSynthesis, startValidationRun, } from "./validation-orchestrator.js";
 export function buildValidationSchemas(deps) {
     const apiNames = (deps.apiProviders ?? []).map(p => p.name);
@@ -194,22 +196,32 @@ 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."),
+        validationId: z
+            .string()
+            .optional()
+            .describe("Optional run id (from the kickoff response) to link this judge job back into the durable validation run."),
     }, {
         title: "Synthesize validation",
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: false,
         openWorldHint: true,
-    }, async ({ question, providerResults, judgeModel }) => textResponse({
-        success: true,
-        tool: "synthesize_validation",
-        readMostly: true,
-        synthesis: startJudgeSynthesis(deps, {
+    }, async ({ question, providerResults, judgeModel, validationId }) => {
+        const synthesis = startJudgeSynthesis(deps, {
             question,
             providerResults,
             judgeProvider: judgeModel,
-        }),
-    }));
+            validationId,
+        });
+        if (validationId)
+            eagerMintFromValidationId(deps, validationId);
+        return textResponse({
+            success: true,
+            tool: "synthesize_validation",
+            readMostly: true,
+            synthesis,
+        });
+    });
     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,
@@ -234,7 +246,8 @@ export function registerValidationTools(server, deps) {
         openWorldHint: false,
     }, async ({ jobId }) => {
         const job = deps.asyncJobManager.getJobSnapshot(jobId);
-        if (!job) {
+        const caller = resolveOwnerPrincipal(getRequestContext());
+        if (!job || !principalCanAccess(deps.asyncJobManager.getJobOwner(jobId), caller)) {
             return textResponse({ success: false, error: "Job not found", jobId });
         }
         return textResponse({ success: true, job });
@@ -259,9 +272,11 @@ export function registerValidationTools(server, deps) {
         openWorldHint: false,
     }, async ({ jobId, provider, maxChars }) => {
         const result = deps.asyncJobManager.getJobResult(jobId, maxChars);
-        if (!result) {
+        const caller = resolveOwnerPrincipal(getRequestContext());
+        if (!result || !principalCanAccess(deps.asyncJobManager.getJobOwner(jobId), caller)) {
             return textResponse({ success: false, error: "Job not found", jobId });
         }
+        eagerMintFromJobId(deps, jobId);
         return textResponse({
             success: true,
             result,
@@ -270,4 +285,38 @@ export function registerValidationTools(server, deps) {
                 : null,
         });
     });
+    if (deps.validationRunStore) {
+        server.tool("validation_receipt", "Retrieve the immutable receipt of a terminal cross-LLM validation run by validationId. Returns minted | pending | expired_unminted | not_found (own-or-not-found).", {
+            validationId: z
+                .string()
+                .min(1)
+                .describe("The run-level validationId from a validation kickoff response (not a job/correlation id)."),
+            format: z
+                .enum(["json", "markdown"])
+                .default("json")
+                .describe("Response format. markdown returns the human-readable rendering (derived on read, never stored or hashed)."),
+            includeRawResponses: z
+                .boolean()
+                .default(false)
+                .describe("Inline full provider answer text (read-time only; pulled live per job under the same owner check; never persisted or hashed)."),
+        }, {
+            title: "Validation receipt",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        }, async ({ validationId, format, includeRawResponses }) => {
+            const result = resolveValidationReceipt(deps, validationId, {
+                caller: currentCaller(),
+                includeRawResponses,
+            });
+            if (format === "markdown" && result.status === "minted") {
+                return {
+                    content: [{ type: "text", text: result.receipt.humanReadable }],
+                    structuredContent: result,
+                };
+            }
+            return textResponse(result);
+        });
+    }
 }

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "llm-cli-gateway",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "llm-cli-gateway",
-      "version": "2.10.0",
+      "version": "2.12.0",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.29.0",
@@ -1066,9 +1066,9 @@
       }
     },
     "node_modules/smol-toml": {
-      "version": "1.6.1",
-      "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.6.1.tgz",
-      "integrity": "sha512-dWUG8F5sIIARXih1DTaQAX4SsiTXhInKf1buxdY9DIg4ZYPZK5nGM1VRIYmEbDbsHt7USo99xSLFu5Q1IqTmsg==",
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.7.0.tgz",
+      "integrity": "sha512-aqVvWoyO21L23mb+drl4RmMXbf6N7FdHjAhTRA9ZBL7apWBgfWC16KjrASI+1p9GAroljyMHj6fK67i0UiTNvQ==",
       "license": "BSD-3-Clause",
       "engines": {
         "node": ">= 18"

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "llm-cli-gateway",
-  "version": "2.11.0",
+  "version": "2.12.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.",
+  "description": "MCP server providing unified access to Claude Code, Codex, Gemini, Grok, Mistral Vibe, and Devin CLIs with session management, retry logic, async job orchestration, durable job results, and cross-LLM validation.",
   "license": "MIT",
   "author": "VerivusAI Labs (https://github.com/verivus-oss)",
   "repository": {
@@ -52,7 +52,13 @@
     "README.md",
     "CHANGELOG.md",
     "socket.yml",
-    "LICENSE"
+    "LICENSE",
+    ".agents/skills/async-job-orchestration/SKILL.md",
+    ".agents/skills/multi-llm-review/SKILL.md",
+    ".agents/skills/session-workflow/SKILL.md",
+    ".agents/skills/secure-orchestration/SKILL.md",
+    ".agents/skills/implement-review-fix/SKILL.md",
+    ".agents/skills/public-demo-session/SKILL.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -105,7 +111,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/better-sqlite3": "^7.6.0",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.0.0",
     "@types/pg": "^8.11.10",
     "@typescript-eslint/eslint-plugin": "^8.61.1",
     "@typescript-eslint/parser": "^8.59.4",

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

@@ -1,43 +0,0 @@
-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>;