consult-mcp 0.4.0 → 0.4.1

package/README.md

@@ -143,11 +143,14 @@ The same calls are available from the shell, which is handy for debugging:
 ```bash
 consult ask codex --model gpt-6-astra "Is the retry logic in src/sync.ts safe under concurrent calls?"
 consult ask codex --resume <session_id> "What would you change first?"
+consult ask grok - < question.md      # long questions from a file or pipe
 consult agents
-consult settings                      # live sessions, and which agents use consult
+consult settings                      # live sessions, task dispatch, and which agents use consult
 ```
 
-Use `npx -y consult-mcp@latest <command>` if it isn't installed globally. `CONSULT_TIMEOUT_SEC` (default 900) caps each advisor call, and `CONSULT_TASK_TIMEOUT_SEC` (default 3600) each dispatched task.
+Use `npx -y consult-mcp@latest <command>` if it isn't installed globally. Advisors are read-only here too: the same containment flags apply, so there is no need to tell them not to edit files. While one works, `consult ask` prints timestamped progress to stderr (commands run and messages for codex and grok, a heartbeat after 30 quiet seconds for any agent) and only the answer to stdout.
+
+`CONSULT_TIMEOUT_SEC` (default 900) caps each advisor call; raise it for long grok runs on large questions. `CONSULT_TASK_TIMEOUT_SEC` (default 3600) caps each dispatched task.
 
 ## Development
 

package/dist/adapters/codex.js

@@ -51,6 +51,25 @@ function parse(stdout) {
         throw new AdvisorError("codex returned no answer");
     return { answer, sessionId: threadId };
 }
+function describe(event) {
+    const item = event.item;
+    if (!item)
+        return undefined;
+    if (event.type === "item.started" && item.type === "command_execution" && item.command)
+        return `$ ${unwrapShell(item.command)}`;
+    if (event.type !== "item.completed")
+        return undefined;
+    switch (item.type) {
+        case "command_execution":
+            return item.exit_code && item.command ? `exit ${item.exit_code}: ${unwrapShell(item.command)}` : undefined;
+        case "file_change":
+            return item.changes?.map((c) => `${c.kind ?? "edit"} ${c.path ?? "?"}`).join(", ");
+        case "agent_message":
+            return item.text;
+        default:
+            return undefined;
+    }
+}
 export const codex = {
     name: "codex",
     command: "codex",
@@ -68,6 +87,7 @@ export const codex = {
         };
     },
     parse,
+    describe,
 };
 export const codexWorker = {
     name: "codex",
@@ -75,24 +95,6 @@ export const codexWorker = {
     build(request, prompt, extraArgs) {
         return { command: "codex", args: ["exec", "--json", "--skip-git-repo-check", ...configArgs(WORKSPACE_WRITE, request, extraArgs), prompt] };
     },
-    describe(event) {
-        const item = event.item;
-        if (!item)
-            return undefined;
-        if (event.type === "item.started" && item.type === "command_execution" && item.command)
-            return `$ ${unwrapShell(item.command)}`;
-        if (event.type !== "item.completed")
-            return undefined;
-        switch (item.type) {
-            case "command_execution":
-                return item.exit_code && item.command ? `exit ${item.exit_code}: ${unwrapShell(item.command)}` : undefined;
-            case "file_change":
-                return item.changes?.map((c) => `${c.kind ?? "edit"} ${c.path ?? "?"}`).join(", ");
-            case "agent_message":
-                return item.text;
-            default:
-                return undefined;
-        }
-    },
+    describe,
     parse,
 };

package/dist/adapters/grok.js

@@ -37,6 +37,25 @@ function parse(stdout) {
     }
     return { answer: result.result, sessionId: result.session_id, ...(typeof model === "string" ? { model } : {}) };
 }
+function describeTool(name, input = {}) {
+    if (name === "run_terminal_cmd" && typeof input.command === "string")
+        return `$ ${unwrapShell(input.command)}`;
+    const target = Object.values(input).find((v) => typeof v === "string");
+    return target ? `${name} ${target}` : name;
+}
+function describe(event) {
+    if (event.type !== "assistant")
+        return undefined;
+    const content = event.message?.content ?? [];
+    const parts = content.flatMap((block) => {
+        if (block.type === "text" && block.text?.trim())
+            return [block.text];
+        if (block.type === "tool_use" && block.name)
+            return [describeTool(block.name, block.input)];
+        return [];
+    });
+    return parts.length > 0 ? parts.join(" · ") : undefined;
+}
 export const grok = {
     name: "grok",
     command: "grok",
@@ -47,30 +66,13 @@ export const grok = {
         return invocation(ADVISOR_TOOLS, request, prompt, ["--resume", sourceSessionId, "--fork-session"]);
     },
     parse,
+    describe,
 };
-function describeTool(name, input = {}) {
-    if (name === "run_terminal_cmd" && typeof input.command === "string")
-        return `$ ${unwrapShell(input.command)}`;
-    const target = Object.values(input).find((v) => typeof v === "string");
-    return target ? `${name} ${target}` : name;
-}
 export const grokWorker = {
     name: "grok",
     build(request, prompt) {
         return invocation(WORKER_TOOLS, request, prompt, ["--session-id", randomUUID()]);
     },
-    describe(event) {
-        if (event.type !== "assistant")
-            return undefined;
-        const content = event.message?.content ?? [];
-        const parts = content.flatMap((block) => {
-            if (block.type === "text" && block.text?.trim())
-                return [block.text];
-            if (block.type === "tool_use" && block.name)
-                return [describeTool(block.name, block.input)];
-            return [];
-        });
-        return parts.length > 0 ? parts.join(" · ") : undefined;
-    },
+    describe,
     parse,
 };

package/dist/cli.js

@@ -8,6 +8,7 @@ import { codex, codexWorker } from "./adapters/codex.js";
 import { grok, grokWorker } from "./adapters/grok.js";
 import { listAgents } from "./agents.js";
 import { createConsult } from "./consult.js";
+import { progressLog } from "./narrate.js";
 import { findOnPath, install, isRegistered, serverCommand, uninstall } from "./install.js";
 import { DEFAULT_SETTINGS, loadSettings, saveSettings, sessionsMode, settingsPath, withSessionsMode } from "./settings.js";
 import { run } from "./run.js";
@@ -21,11 +22,14 @@ import { AGENTS, EFFORTS, SESSION_ID_PATTERN } from "./types.js";
 import { VERSION } from "./version.js";
 const DEFAULT_TIMEOUT_SEC = 900;
 const DEFAULT_TASK_TIMEOUT_SEC = 3600;
+const HEARTBEAT_MS = 30_000;
 const USAGE = `consult ${VERSION} - let coding agents ask each other for advice
 
   consult serve                          run the MCP server (stdio)
   consult ask <agent> [options] <question...>
+                                         ask an advisor; it can read --cwd but never change anything
       --model <id>  --effort low|medium|high  --resume <session_id>  --cwd <dir>
+      a question of "-" is read from stdin; progress goes to stderr, the answer alone to stdout
   consult agents                         list installed CLIs and models
   consult install [--sessions off|repo|machine]
                                          register the MCP server with claude, codex and grok
@@ -33,7 +37,8 @@ const USAGE = `consult ${VERSION} - let coding agents ask each other for advice
   consult settings                       live sessions, task dispatch, and which agents use consult (interactive)
 
 agents: ${AGENTS.join(", ")}
-timeouts: CONSULT_TIMEOUT_SEC per advisor call (default ${DEFAULT_TIMEOUT_SEC}), CONSULT_TASK_TIMEOUT_SEC per task (default ${DEFAULT_TASK_TIMEOUT_SEC})`;
+timeouts: CONSULT_TIMEOUT_SEC per advisor call (default ${DEFAULT_TIMEOUT_SEC}; raise it for long grok runs),
+          CONSULT_TASK_TIMEOUT_SEC per task (default ${DEFAULT_TASK_TIMEOUT_SEC})`;
 function secondsFromEnv(name, defaultSec) {
     const raw = process.env[name];
     const sec = raw ? Number(raw) : defaultSec;
@@ -102,6 +107,12 @@ async function serve() {
     }
     await server.connect(transport);
 }
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
 async function askCommand(argv) {
     const { values, positionals } = parseArgs({
         args: [...argv],
@@ -117,14 +128,23 @@ async function askCommand(argv) {
         throw new Error("--resume must be a session id: letters, digits and hyphens, not starting with a hyphen");
     }
     refuseLive(values.resume);
-    const result = await consult().ask({
-        agent: agent,
-        question: words.join(" "),
-        cwd: values.cwd ?? process.cwd(),
-        model: values.model,
-        effort: values.effort,
-        sessionId: values.resume,
-    });
+    const question = words.length === 1 && words[0] === "-" ? await readStdin() : words.join(" ");
+    const progress = progressLog((line) => process.stderr.write(line), `${agent} is still working`, HEARTBEAT_MS);
+    progress.update(`asking ${agent} (read-only)`);
+    let result;
+    try {
+        result = await consult().ask({
+            agent: agent,
+            question,
+            cwd: values.cwd ?? process.cwd(),
+            model: values.model,
+            effort: values.effort,
+            sessionId: values.resume,
+        }, undefined, progress.update);
+    }
+    finally {
+        progress.stop();
+    }
     process.stdout.write(`${result.answer}\n`);
     process.stderr.write(`\n[${result.agent}${result.model ? ` ${result.model}` : ""} · session ${result.sessionId} · ${(result.durationMs / 1000).toFixed(1)}s]\n`);
 }

package/dist/consult.js

@@ -1,4 +1,5 @@
 import { statSync } from "node:fs";
+import { describeLine } from "./narrate.js";
 import { frameForkPrompt, framePrompt } from "./prompt.js";
 import { AdvisorError, } from "./types.js";
 const STDERR_TAIL = 2000;
@@ -38,20 +39,32 @@ export function assertExitedCleanly(agent, res, timeoutMs) {
     }
 }
 export function createConsult({ run, adapters, timeoutMs }) {
-    async function execute(adapter, request, invoke, signal) {
+    async function execute(adapter, request, invoke, signal, onUpdate) {
         validate(request);
         const started = Date.now();
         // Computed per call, never cached: containment must reflect the config as it is right now.
         const extraArgs = adapter.prepare ? await adapter.prepare(run, request.cwd, signal) : [];
         const invocation = invoke(extraArgs);
-        const res = await run(invocation.command, invocation.args, { cwd: request.cwd, timeoutMs, signal });
-        assertExitedCleanly(adapter.name, res, timeoutMs);
-        return { agent: adapter.name, ...adapter.parse(res.stdout), durationMs: Date.now() - started };
+        const { describe } = adapter;
+        const lines = [];
+        const onStdoutLine = onUpdate && describe
+            ? (line) => {
+                lines.push(line);
+                const text = describeLine(describe, line);
+                if (text)
+                    onUpdate(text);
+            }
+            : undefined;
+        const res = await run(invocation.command, invocation.args, { cwd: request.cwd, timeoutMs, signal, onStdoutLine });
+        const stdout = onStdoutLine ? lines.join("\n") : res.stdout;
+        assertExitedCleanly(adapter.name, { ...res, stdout }, timeoutMs);
+        return { agent: adapter.name, ...adapter.parse(stdout), durationMs: Date.now() - started };
     }
-    async function ask(request, signal) {
+    /** `onUpdate` receives one-line progress updates for CLIs that stream their work (codex, grok). */
+    async function ask(request, signal, onUpdate) {
         const adapter = adapters[request.agent];
         const prompt = framePrompt(request.question, Boolean(request.sessionId));
-        return execute(adapter, request, (extra) => adapter.build(request, prompt, extra), signal);
+        return execute(adapter, request, (extra) => adapter.build(request, prompt, extra), signal, onUpdate);
     }
     /** Asks a read-only fork of a live session. It runs in that session's directory, where its CLI can find it. */
     async function askSession(target, question, effort, signal) {

package/dist/narrate.js

@@ -1,10 +1,42 @@
+import { parseJsonLines } from "./jsonl.js";
 const MAX_UPDATE_CHARS = 200;
 /** Collapses whitespace and shortens text to a single progress line. */
 export function oneLine(text, max = MAX_UPDATE_CHARS) {
     const flat = text.replace(/\s+/g, " ").trim();
     return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
 }
+/**
+ * Turns one line of a CLI's JSONL output into a progress line, if it is worth reporting.
+ * Never throws: a malformed event must not break the run it came from.
+ */
+export function describeLine(describe, line) {
+    try {
+        const [event] = parseJsonLines(line);
+        const text = event ? describe(event)?.trim() : undefined;
+        return text ? oneLine(text) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** `/bin/zsh -lc 'npm test'` → `npm test`: CLIs wrap every command in a login shell. */
 export function unwrapShell(command) {
     return /^\S*sh -lc '(.*)'$/s.exec(command)?.[1] ?? command;
 }
+/**
+ * A timestamped progress log for the shell: each update as one line, plus a heartbeat whenever nothing has been
+ * written for `heartbeatMs`, so a long quiet run still shows it is alive. Call stop() when the run ends.
+ */
+export function progressLog(write, heartbeat, heartbeatMs) {
+    const started = Date.now();
+    let last = started;
+    const update = (text) => {
+        last = Date.now();
+        write(`[${Math.round((last - started) / 1000)}s] ${text}\n`);
+    };
+    const timer = setInterval(() => {
+        if (Date.now() - last >= heartbeatMs)
+            update(heartbeat);
+    }, Math.max(1, Math.round(heartbeatMs / 3)));
+    return { update, stop: () => clearInterval(timer) };
+}

package/dist/tasks.js

@@ -1,6 +1,5 @@
 import { assertDirectory, assertExitedCleanly } from "./consult.js";
-import { parseJsonLines } from "./jsonl.js";
-import { oneLine } from "./narrate.js";
+import { describeLine } from "./narrate.js";
 import { frameTaskPrompt } from "./prompt.js";
 import { AdvisorError } from "./types.js";
 const MAX_UPDATES = 200;
@@ -40,21 +39,13 @@ export function createTaskManager({ run, workers, timeoutMs, signal, now = Date.
         }
     }
     function narrate(id, worker, line) {
-        // A malformed event must never break the run, so narration failures are dropped.
-        try {
-            const [event] = parseJsonLines(line);
-            const text = event ? worker.describe(event)?.trim() : undefined;
-            if (!text)
-                return;
-            change(id, (view) => {
-                const seq = (view.updates.at(-1)?.seq ?? 0) + 1;
-                const next = { seq, atMs: now() - view.startedAt, text: oneLine(text) };
-                return { ...view, updates: [...view.updates, next].slice(-MAX_UPDATES) };
-            });
-        }
-        catch {
-            // Ignored, see above.
-        }
+        const text = describeLine((event) => worker.describe(event), line);
+        if (!text)
+            return;
+        change(id, (view) => {
+            const seq = (view.updates.at(-1)?.seq ?? 0) + 1;
+            return { ...view, updates: [...view.updates, { seq, atMs: now() - view.startedAt, text }].slice(-MAX_UPDATES) };
+        });
     }
     function finish(id, outcome) {
         change(id, (view) => ({ ...view, ...outcome, finishedAt: now() }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "consult-mcp",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "MCP server that lets Claude Code, Codex and Grok ask each other for a second opinion through the CLIs already signed in on your machine",
   "keywords": [
     "mcp",