crosscheck-mcp 0.2.1 → 0.2.2

package/dist/node-stdio.cjs

@@ -2113,7 +2113,9 @@ var ROUTABLE_TOOLS = [
   "delegate",
   "bench",
   "config_pin",
-  "update_crosscheck"
+  "update_crosscheck",
+  // Help
+  "help"
 ];
 var DEFAULT_TOOL = "confer";
 function renderInstructions() {
@@ -2122,7 +2124,7 @@ function renderInstructions() {
 When the user message begins with \`xc\` or \`XC\` followed by a space (or is exactly \`xc\`/\`XC\`), treat it as an explicit invocation of this server.
 
 Routing rules:
-1. If the next whitespace-delimited token matches one of the tool names below, call \`mcp__crosscheck__<that name>\` and pass the remainder of the message as the natural-language input for that tool's primary argument (\`instruction\` for create/orchestrate/plan; \`question\` for confer/debate/coordinate/triangulate; \`output_to_audit\` for audit/review/critique; \`expr\` for verify; \`prompt\` for pick/solve; the obvious slot for the rest).
+1. If the next whitespace-delimited token matches one of the tool names below, call \`mcp__crosscheck__<that name>\` and pass the remainder of the message as the natural-language input for that tool's primary argument (\`instruction\` for create/orchestrate/plan; \`question\` for confer/debate/coordinate/triangulate; \`output_to_audit\` for audit/review/critique; \`expr\` for verify; \`prompt\` for pick/solve; \`command\` for help \u2014 and \`xc help\` alone calls help with no args; the obvious slot for the rest).
 2. If the next token does NOT match a tool name (or there is no next token), default to \`mcp__crosscheck__${DEFAULT_TOOL}\` and pass the entire message tail (everything after \`xc\`/\`XC\`) as \`question\`.
 3. Preserve the user's wording verbatim in the argument \u2014 do not paraphrase, summarize, or "clean up" the prompt before forwarding.
 4. If the user message is exactly \`xc\` or \`XC\` with no tail, ask them what they want crosscheck to do; do not invent a question.
@@ -2133,6 +2135,7 @@ Examples:
 - \`xc audit the diff in this PR\` \u2192 \`mcp__crosscheck__audit({ output_to_audit: "the diff in this PR" })\`
 - \`xc plan the migration from REST to gRPC\` \u2192 \`mcp__crosscheck__plan({ instruction: "the migration from REST to gRPC" })\`
 - \`xc verify x > 0 when x = 5\` \u2192 \`mcp__crosscheck__verify({ expr: "x > 0 when x = 5" })\`
+- \`xc help\` \u2192 \`mcp__crosscheck__help({})\` (lists every command); \`xc help debate\` \u2192 \`mcp__crosscheck__help({ command: "debate" })\`
 - \`xc what's the right caching strategy here?\` \u2192 \`mcp__crosscheck__${DEFAULT_TOOL}({ question: "what's the right caching strategy here?" })\` (no tool name match \u2192 default to ${DEFAULT_TOOL})
 - \`XC how risky is this refactor?\` \u2192 same default-to-${DEFAULT_TOOL} behavior
 
@@ -12225,7 +12228,7 @@ var CHECK_INTERVAL_SECONDS = 3 * 24 * 60 * 60;
 var DEFAULT_PACKAGE = "crosscheck-cli";
 var FETCH_TIMEOUT_MS = 3e3;
 function engineVersion() {
-  return true ? "0.2.1" : "0.0.0-dev";
+  return true ? "0.2.2" : "0.0.0-dev";
 }
 function defaultUpdateCachePath() {
   const base = process.env["CROSSCHECK_DATA_DIR"] || import_node_path13.default.join(import_node_os2.default.homedir() || import_node_os2.default.tmpdir(), ".crosscheck");
@@ -12643,6 +12646,267 @@ async function runTriangulate(args, opts) {
   return result;
 }
 
+// src/core/help-catalog.ts
+init_cjs_shims();
+var SUITE_OVERVIEW = "Crosscheck is a multi-LLM orchestration layer for your terminal. It runs structured patterns \u2014 ask a panel in parallel, debate, cross-examine, plan, audit, build \u2014 across Anthropic, OpenAI, Google (Gemini), xAI (Grok), Mistral, Groq, and DeepSeek, using your own API keys. You invoke it from Claude Code with an `xc` (or `XC`) prefix, e.g. `xc debate <topic>`. A bare `xc <question>` with no command defaults to `confer` (ask the whole panel).";
+var HELP_CATEGORIES = [
+  "Ask & deliberate",
+  "Plan, build & review",
+  "Single-shot utilities",
+  "Memory & introspection",
+  "Operations",
+  "Help"
+];
+var HELP_CATALOG = [
+  // ── Ask & deliberate ──────────────────────────────────────────────
+  {
+    name: "confer",
+    category: "Ask & deliberate",
+    primaryArg: "question",
+    summary: "Ask the whole panel the same question in parallel and see every answer.",
+    example: "xc confer what's the best caching strategy for this API?",
+    detail: "Sends your question to every active provider at once and returns each model's answer side by side (plus an optional synthesis). Best for a fast, diverse read on an open question. This is also the default when you type `xc <something>` with no command."
+  },
+  {
+    name: "debate",
+    category: "Ask & deliberate",
+    primaryArg: "topic",
+    summary: "Bounded multi-round debate between models, ending in a synthesized recommendation.",
+    example: "xc debate should we adopt a monorepo?",
+    detail: `The panel argues across a few rounds \u2014 each model sees the others' prior turns, concedes or pushes back \u2014 then a moderator synthesizes a single grounded recommendation. Supports reasoning:"max" to bump the moderator synthesis seat to Fable 5. Great for contentious or trade-off-heavy calls.`
+  },
+  {
+    name: "coordinate",
+    category: "Ask & deliberate",
+    primaryArg: "question",
+    summary: "Proposer \u2192 critics \u2192 synthesizer pipeline for a vetted answer.",
+    example: "xc coordinate design a rate limiter for our gateway",
+    detail: "One model drafts a proposal, others critique it, and a synthesizer merges the critique into a final answer. More structured than confer/debate when you want a single reviewed deliverable rather than a spread of opinions."
+  },
+  {
+    name: "triangulate",
+    category: "Ask & deliberate",
+    primaryArg: "question",
+    summary: "Consensus + weighted confidence + a minority report across the panel.",
+    example: "xc triangulate is this migration plan safe to ship Friday?",
+    detail: "Runs the coordinate pipeline and reports where the panel agrees (consensus + weighted confidence), the key claims, and a minority report of dissenting views. Best when you need a defensible, confidence-scored verdict and want to see what the outliers think."
+  },
+  // ── Plan, build & review ──────────────────────────────────────────
+  {
+    name: "plan",
+    category: "Plan, build & review",
+    primaryArg: "goal",
+    summary: "Collaborative step-by-step plan (steps, risks, alternatives) across models.",
+    example: "xc plan migrate our REST API to gRPC",
+    detail: 'Produces a numbered plan with risks and alternatives considered, built on the debate engine. Supports reasoning:"max" to run the plan synthesis on Fable 5 for the hardest planning.'
+  },
+  {
+    name: "audit",
+    category: "Plan, build & review",
+    primaryArg: "output_to_audit",
+    summary: "Score a piece of output against a rubric (single- or multi-judge).",
+    example: "xc audit <paste a design doc or diff>",
+    detail: 'An independent auditor (or a panel of judges) scores the given output against a rubric \u2014 correctness, clarity, security, etc. \u2014 and returns per-item pass/fail with rationale and an overall score. reasoning:"max" runs the auditor on Fable 5.'
+  },
+  {
+    name: "review",
+    category: "Plan, build & review",
+    primaryArg: "output_to_audit",
+    summary: "Lighter-weight peer review of output; narrative feedback.",
+    example: "xc review this function for edge cases",
+    detail: "A less formal cousin of audit: the panel reads your output and returns prose feedback rather than a scored rubric. Good for a quick second set of eyes."
+  },
+  {
+    name: "critique",
+    category: "Plan, build & review",
+    primaryArg: "output_to_audit",
+    summary: "Focused, pointed critique of a specific artifact.",
+    example: "xc critique our onboarding email copy",
+    detail: "Asks the panel to find what's weak, wrong, or missing in the given artifact. Sharper and more adversarial than review."
+  },
+  {
+    name: "orchestrate",
+    category: "Plan, build & review",
+    primaryArg: "goal",
+    summary: "Plan a task DAG and execute it across models, then recombine.",
+    example: "xc orchestrate build a landing page with copy, layout, and SEO",
+    detail: 'Decomposes a goal into a dependency graph of subtasks, runs them across providers (in parallel where possible), then synthesizes the results. reasoning:"max" runs the recombine/synthesis seat on Fable 5.'
+  },
+  {
+    name: "create",
+    category: "Plan, build & review",
+    primaryArg: "instruction",
+    summary: "End-to-end macro: scope \u2192 build \u2192 review \u2192 audit.",
+    example: "xc create a Python script that dedupes a CSV by email",
+    detail: "The full lifecycle in one call \u2014 scopes the work, builds it, reviews, and audits the result. Use `create_cheap` for the same flow routed through cheaper models."
+  },
+  {
+    name: "create_cheap",
+    category: "Plan, build & review",
+    primaryArg: "instruction",
+    summary: "Like create, but routes work through the cheap-tier model ladder.",
+    example: "xc create_cheap a regex that validates US phone numbers",
+    detail: "Same scope \u2192 build \u2192 review \u2192 audit lifecycle as create, but uses the cheap tier (e.g. Gemini 3.5 Flash, GPT-5-mini, Claude Haiku) to keep cost down for routine work."
+  },
+  // ── Single-shot utilities ─────────────────────────────────────────
+  {
+    name: "pick",
+    category: "Single-shot utilities",
+    primaryArg: "prompt",
+    summary: "Have the panel vote among options and return the winner + tally.",
+    example: "xc pick Postgres vs MySQL vs SQLite for a single-tenant app",
+    detail: "Give it a decision + options (and optional criteria); each model votes, and you get the winning choice with the per-provider tally and rationale."
+  },
+  {
+    name: "solve",
+    category: "Single-shot utilities",
+    primaryArg: "prompt",
+    summary: "Iterative solver: generate \u2192 verify \u2192 retry until it passes.",
+    example: "xc solve write a function that parses ISO-8601 durations (with tests)",
+    detail: 'Generates a solution, runs it against a verifier (regex or a sandboxed shell command), and retries with the failure feedback until it passes or hits max attempts. With a target path it returns a unified-diff patch. reasoning:"max" routes the solver to Fable 5.'
+  },
+  {
+    name: "verify",
+    category: "Single-shot utilities",
+    primaryArg: "expr",
+    summary: "Check a claim/expression and return a structured true/false verdict.",
+    example: "xc verify 2^10 > 1000",
+    detail: "Evaluates a factual or logical expression and returns a structured verdict with reasoning. Some checks (shell, URL-head) can run in a sandbox."
+  },
+  {
+    name: "fetch",
+    category: "Single-shot utilities",
+    primaryArg: "url",
+    summary: "Fetch a URL's content for use as grounding context.",
+    example: "xc fetch https://example.com/spec",
+    detail: "Retrieves and cleans a URL's content so it can be fed into other tools as context. Subject to the configured fetch/egress policy."
+  },
+  // ── Memory & introspection ────────────────────────────────────────
+  {
+    name: "recall",
+    category: "Memory & introspection",
+    primaryArg: "query",
+    summary: "Search past sessions/transcripts for prior work.",
+    example: "xc recall what did we decide about auth tokens?",
+    detail: "Full-text search over archived transcripts and session memory so the panel (and you) can pick up prior decisions. Requires local storage."
+  },
+  {
+    name: "session_memory",
+    category: "Memory & introspection",
+    primaryArg: "action",
+    summary: "Read/write carry-forward notes that persist across a session.",
+    example: "xc session_memory list",
+    detail: "Stores and retrieves durable notes for the current session so multi-step work keeps context. Requires local storage."
+  },
+  {
+    name: "scoreboard",
+    category: "Memory & introspection",
+    primaryArg: "(none)",
+    summary: "Leaderboard of provider win-rates, usage, and stats.",
+    example: "xc scoreboard",
+    detail: "Aggregates ballots, delegations, and usage across your history into a per-provider leaderboard. Powers the smart router's weighting. Requires local storage."
+  },
+  {
+    name: "explain",
+    category: "Memory & introspection",
+    primaryArg: "session_id",
+    summary: "Break down what a session/tool call did, cost, and timing.",
+    example: "xc explain the last debate",
+    detail: "Returns a per-purpose and per-provider breakdown of calls, tokens, cost, and wall/cpu time for a session or run. Requires local storage."
+  },
+  // ── Operations ────────────────────────────────────────────────────
+  {
+    name: "list_providers",
+    category: "Operations",
+    primaryArg: "(none)",
+    summary: "Show configured providers, their default models, and active status.",
+    example: "xc list_providers",
+    detail: "Lists every provider Crosscheck knows about, which have keys configured, each one's default model, and whether it's active in the panel."
+  },
+  {
+    name: "recommend_panel",
+    category: "Operations",
+    primaryArg: "task",
+    summary: "Suggest which providers/models to use for a given task.",
+    example: "xc recommend_panel a security audit of a smart contract",
+    detail: "Recommends a panel composition (which providers + tiers) suited to the task, using historical performance where available."
+  },
+  {
+    name: "delegate",
+    category: "Operations",
+    primaryArg: "task",
+    summary: "Route a task to the single best-fit provider instead of the whole panel.",
+    example: "xc delegate summarize this 40-page RFC",
+    detail: "Picks the most suitable single model for the task (by capability + scoreboard weighting) and runs it there \u2014 cheaper than a full panel when one voice is enough."
+  },
+  {
+    name: "bench",
+    category: "Operations",
+    primaryArg: "(none)",
+    summary: "Run provider benchmarks against golden tasks.",
+    example: "xc bench",
+    detail: "Runs the configured golden benchmark set across providers to measure quality/latency/cost, feeding the scoreboard."
+  },
+  {
+    name: "config_pin",
+    category: "Operations",
+    primaryArg: "action",
+    summary: "Pin/verify the hash of canonical config files (pricing, config).",
+    example: "xc config_pin status",
+    detail: "Manages a ledger of expected config-file hashes so unexpected drift in pricing.json / crosscheck.config.json is detected."
+  },
+  {
+    name: "update_crosscheck",
+    category: "Operations",
+    primaryArg: "(none)",
+    summary: "Check for and report available Crosscheck updates.",
+    example: "xc update_crosscheck",
+    detail: "Checks whether a newer crosscheck-cli / engine is published and tells you how to upgrade."
+  },
+  // ── Help ──────────────────────────────────────────────────────────
+  {
+    name: "help",
+    category: "Help",
+    primaryArg: "command",
+    summary: "List all commands, or explain one in detail.",
+    example: "xc help   \xB7   xc help debate",
+    detail: "`xc help` lists every command grouped by category. `xc help <command>` shows the full description, primary argument, and an example for that one command."
+  }
+];
+var BY_NAME = new Map(HELP_CATALOG.map((e) => [e.name, e]));
+function lookupHelp(command) {
+  const c = command.trim().toLowerCase().replace(/^xc\s+/, "").replace(/[^a-z_]/g, "");
+  return BY_NAME.get(c) ?? null;
+}
+function renderHelpOverview() {
+  const lines = [SUITE_OVERVIEW, ""];
+  const nameW = Math.max(...HELP_CATALOG.map((e) => e.name.length));
+  for (const category of HELP_CATEGORIES) {
+    const entries = HELP_CATALOG.filter((e) => e.category === category);
+    if (entries.length === 0) continue;
+    lines.push(`${category}:`);
+    for (const e of entries) {
+      lines.push(`  xc ${e.name.padEnd(nameW)}  ${e.summary}`);
+    }
+    lines.push("");
+  }
+  lines.push("Run `xc help <command>` for details on any one command (e.g. `xc help debate`).");
+  lines.push(
+    'Tip: a bare `xc <question>` with no command asks the whole panel (confer). Reasoning tools (plan, solve, debate, orchestrate, audit, triangulate) accept reasoning:"max" to bump the lead seat to Fable 5.'
+  );
+  return lines.join("\n");
+}
+function renderHelpCommand(entry) {
+  return [
+    `xc ${entry.name} \u2014 ${entry.summary}`,
+    "",
+    entry.detail,
+    "",
+    `Primary argument: ${entry.primaryArg}`,
+    `Example: ${entry.example}`
+  ].join("\n");
+}
+
 // src/tools/index.ts
 function defineTool(opts) {
   return {
@@ -12685,6 +12949,49 @@ function zodToJsonSchema(schema) {
   if (schema instanceof import_zod.z.ZodDefault) return zodToJsonSchema(schema._def.innerType);
   return {};
 }
+function helpTool() {
+  return defineTool({
+    name: "help",
+    description: 'List all Crosscheck commands and what they do, or explain one command. Call with no args for the full catalog; pass `command` (e.g. "debate") for detail on a single command. Routed from `xc help` / `xc help <command>`.',
+    schema: import_zod.z.object({ command: import_zod.z.string().optional() }),
+    handler: async ({ command }) => {
+      const query = (command ?? "").trim();
+      if (query) {
+        const entry = lookupHelp(query);
+        if (entry) {
+          return {
+            tool: "help",
+            command: entry.name,
+            summary: entry.summary,
+            detail: entry.detail,
+            primary_arg: entry.primaryArg,
+            example: entry.example,
+            display_text: renderHelpCommand(entry)
+          };
+        }
+        return {
+          tool: "help",
+          unknown_command: query,
+          commands: HELP_CATALOG.map((e) => e.name),
+          display_text: `Unknown command "${query}". Here are all Crosscheck commands:
+
+` + renderHelpOverview()
+        };
+      }
+      return {
+        tool: "help",
+        overview: SUITE_OVERVIEW,
+        commands: HELP_CATALOG.map((e) => ({
+          name: e.name,
+          category: e.category,
+          summary: e.summary,
+          example: e.example
+        })),
+        display_text: renderHelpOverview()
+      };
+    }
+  });
+}
 function registerCoreTools(opts = {}) {
   const o = opts && typeof opts === "object" && "toolNames" in opts ? { bridge: opts } : opts;
   const tools = /* @__PURE__ */ new Map();
@@ -12806,7 +13113,8 @@ function registerCoreTools(opts = {}) {
       o.nodeCache
     ),
     createTool(o, "create", false),
-    createTool(o, "create_cheap", true)
+    createTool(o, "create_cheap", true),
+    helpTool()
   ];
   for (const t of list) tools.set(t.name, t);
   return tools;
@@ -13772,15 +14080,18 @@ async function flush() {
 
 // src/server.ts
 var SERVER_NAME = "crosscheck-agent";
-var SERVER_VERSION = true ? "0.2.1" : "0.0.0-dev";
+var SERVER_VERSION = true ? "0.2.2" : "0.0.0-dev";
 function extractRunSummaryText(out) {
   if (out === null || typeof out !== "object" || Array.isArray(out)) return void 0;
-  const rs = out["run_summary"];
-  if (rs === null || typeof rs !== "object" || Array.isArray(rs)) return void 0;
-  const text = rs["text"];
-  if (typeof text !== "string") return void 0;
-  const trimmed = text.trim();
-  return trimmed === "" ? void 0 : text;
+  const rec = out;
+  const rs = rec["run_summary"];
+  if (rs !== null && typeof rs === "object" && !Array.isArray(rs)) {
+    const text = rs["text"];
+    if (typeof text === "string" && text.trim() !== "") return text;
+  }
+  const display = rec["display_text"];
+  if (typeof display === "string" && display.trim() !== "") return display;
+  return void 0;
 }
 function createServer(opts = {}) {
   const server = new import_server2.Server(