@sghanavati/relay-mcp 0.1.2 → 0.1.4

package/README.md

@@ -138,12 +138,111 @@ Typical response payload:
 }
 ```
 
+## Use Cases
+
+### 1. Context-Preserving Orchestration
+Keep Claude's planning session lean by delegating implementation work to Codex.
+Claude holds the architecture; Codex executes the sub-tasks without polluting the
+orchestrator's context window.
+
+```javascript
+delegate({
+  task: "Implement the auth middleware per the spec in PLAN.md",
+  workdir: "/path/to/repo"
+});
+```
+
+### 2. Batch Code Generation
+Generate multiple independent artifacts — components, migrations, API routes — each
+in a fresh Codex context. The orchestrator's growing session history never bleeds into
+the worker's input.
+
+```javascript
+delegate({
+  task: "Generate CRUD routes for users, posts, and comments in src/routes/",
+  workdir: "/path/to/repo"
+});
+```
+
+### 3. Test Generation from Spec
+After a feature is built, delegate test writing as a standalone, self-contained task.
+
+```javascript
+delegate({
+  task: "Write Jest unit tests for src/auth/middleware.ts covering success, expired token, and missing token cases",
+  workdir: "/path/to/repo"
+});
+```
+
+### 4. Scoped Refactoring
+Delegate well-defined refactors without polluting the main session with diff noise.
+
+```javascript
+delegate({
+  task: "Migrate all fetch() calls in src/api/ to use the axios client",
+  workdir: "/path/to/repo"
+});
+```
+
+### 5. Documentation Generation
+Auto-generate JSDoc, API docs, or README sections for a module after implementation.
+
+```javascript
+delegate({
+  task: "Add JSDoc comments to all exported functions in src/utils/",
+  workdir: "/path/to/repo"
+});
+```
+
+### 6. Plan-Driven Execution (Orchestrator Pattern)
+Use Claude as the planning engine and relay-mcp as the execution bridge.
+Each task in a written plan maps to a `delegate` call; Claude reviews `files_changed`
+before moving to the next task.
+
+```
+Plan phase  → Claude writes task specs
+Execute     → delegate each task to Codex
+Review      → Claude reads files_changed, verifies output
+Repeat      → next task
+```
+
+### When not to use it
+- Tasks that require back-and-forth decisions mid-execution (Codex runs `--full-auto`)
+- Work that needs full conversation context (Codex sees only what you pass in `task`/`context`)
+- Very short one-liners where the delegation roundtrip (Codex startup + execution) exceeds the time to do it inline
+
+## Orchestration with tmux + dmux
+
+[dmux](https://dmux.ai) (`npm install -g dmux`) arranges a tmux layout where Claude Code
+orchestrates from one pane while Codex sessions run in adjacent panes.
+
+```
+tmux window
+├── pane 0  Claude Code  — GSD orchestrator, relay-mcp registered
+├── pane 1  tail -f <relay-log>   live output from task 1
+├── pane 2  tail -f <relay-log>   live output from task 2
+└── ...
+```
+
+**The loop:**
+1. CC writes a plan (GSD), then fires `delegate` calls — one per task
+2. relay-mcp spawns Codex for each and returns `files_changed` + output when done
+3. *(Phase 3)* Each task streams output to a log file; adjacent panes `tail -f` those logs live
+4. CC reads `files_changed`, verifies output, moves to the next task
+5. You supervise only CC — Codex runs unattended
+
+> **Note:** Live log streaming (`meta.log_file`) lands in Phase 3. Steps 1, 2, 4, and 5 work today.
+
 ## Configuration
 | Variable | Default | Description |
 | --- | --- | --- |
 | `RELAY_CODEX_PATH` | `codex` from `PATH` | Full path to Codex binary for PATH-limited environments (especially Claude Desktop). |
 | `RELAY_LOG_LEVEL` | `info` | Startup log verbosity control. `error` suppresses the ready banner; other values show it. |
 
+### Provider model requirement
+- `provider: "codex"`: `model` is optional.
+- `provider: "openrouter"` or `provider: "lmstudio"`: `model` is required.
+
 ## Troubleshooting
 ### 1) PATH issues (Codex not found)
 Symptom:
@@ -179,9 +278,18 @@ Fix:
 - Confirm network/DNS connectivity and any proxy requirements.
 - Re-run `codex login` if your session may have expired.
 
+### 4) `npx` from this package's own repo root
+Symptom:
+`sh: relay-mcp: command not found` when running `npx -y @sghanavati/relay-mcp` from inside the `relay-mcp` source checkout.
+
+Fix:
+
+- For local development in this repo, run `node dist/index.js` instead.
+- For published-package verification, run from any other directory (or use `npm --prefix /tmp exec --yes --package=@sghanavati/relay-mcp -- relay-mcp --version`).
+
 ## Security
 - `relay-mcp` only delegates work inside the `workdir` you pass to `delegate`.
-- `workdir` values are canonicalized with `path.resolve()` before subprocess execution (SAFE-01 / CVE-2025-59532 mitigation).
+- `workdir` values are canonicalized with `path.resolve()` before subprocess execution.
 - Codex runs with `--full-auto` and can read/write files in that delegated directory.
 - `relay-mcp` does not store credentials, API keys, or session tokens; authentication remains in Codex CLI.
 

package/dist/config/providers.js

@@ -0,0 +1,9 @@
+export function getOpenRouterApiKey() {
+    return process.env["OPENROUTER_API_KEY"]?.trim() || null;
+}
+export function getLmStudioEndpoint() {
+    return process.env["LMSTUDIO_ENDPOINT"]?.trim() || "http://localhost:1234";
+}
+export function getLmStudioApiKey() {
+    return process.env["LMSTUDIO_API_KEY"]?.trim() || null;
+}

package/dist/contracts/delegate.js

@@ -3,10 +3,11 @@ const delegateSchemaShape = {
     task: z.string().min(1).describe("The coding task to delegate to the worker"),
     workdir: z.string().describe("Absolute path to the working directory"),
     provider: z
-        .enum(["codex"])
+        .enum(["codex", "openrouter", "lmstudio"])
         .optional()
         .default("codex")
-        .describe("Worker provider (currently only codex)"),
+        .describe("Worker provider. 'codex' = agentic execution (modifies files). " +
+        "'openrouter' and 'lmstudio' = generation-only (text response, no file changes)."),
     context: z
         .string()
         .optional()
@@ -20,7 +21,7 @@ const delegateSchemaShape = {
     model: z
         .string()
         .optional()
-        .describe("Model override for the provider (e.g., o4-mini for Codex)"),
+        .describe("Model override. Optional for 'codex'. Required for 'openrouter' and 'lmstudio' (pass an explicit provider model ID)."),
 };
 const delegateArgsSchema = z.object(delegateSchemaShape);
 export const delegateSchema = delegateArgsSchema.shape;

package/dist/server.js

@@ -3,13 +3,15 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { delegateSchema } from "./contracts/delegate.js";
 import { validateStartup } from "./startup.js";
 import { handleDelegate } from "./tools/delegate.js";
+import { handleCheckWorkers } from "./tools/check_workers.js";
 export async function startServer() {
-    await validateStartup();
     const server = new McpServer({
         name: "relay-mcp",
         version: "1.0.0",
     });
     server.tool("delegate", delegateSchema, async (args) => handleDelegate(args));
+    server.tool("check_workers", {}, async () => handleCheckWorkers());
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    await validateStartup();
 }

package/dist/startup.js

@@ -1,52 +1,16 @@
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-import { MIN_CODEX_VERSION } from "./config/constants.js";
-import { getCodexBin, getRelayLogLevel } from "./config/runtime.js";
-const execFileAsync = promisify(execFile);
+import { getRelayLogLevel } from "./config/runtime.js";
+import { diagnoseCodexWorker } from "./workers/diagnostics.js";
 function shouldPrintReadyBanner() {
     return getRelayLogLevel() !== "error";
 }
-function isVersionBelow(version, min) {
-    const match = version.match(/(\d+)\.(\d+)\.(\d+)/);
-    if (!match)
-        return true;
-    const [, maj, min_, pat] = match.map(Number);
-    if (maj !== min[0])
-        return maj < min[0];
-    if (min_ !== min[1])
-        return min_ < min[1];
-    return pat < min[2];
-}
 export async function validateStartup() {
-    const failures = [];
-    let codexVersion = "";
-    const codexBin = getCodexBin();
-    const configuredPath = process.env.RELAY_CODEX_PATH?.trim();
-    try {
-        const { stdout } = await execFileAsync(codexBin, ["--version"]);
-        codexVersion = stdout.trim();
-    }
-    catch {
-        const binaryHint = configuredPath
-            ? `RELAY_CODEX_PATH=${configuredPath}`
-            : "PATH (default `codex` binary)";
-        failures.push(`Error: Codex binary not found via ${binaryHint}.
-Fix: run \`npm install -g @openai/codex\` or set \`RELAY_CODEX_PATH=/full/path/to/codex\` in your MCP config, then restart relay-mcp.`);
-    }
-    if (codexVersion && isVersionBelow(codexVersion, MIN_CODEX_VERSION)) {
-        failures.push(`Error: Codex version ${codexVersion} is below minimum 0.39.0.\nFix: run \`npm install -g @openai/codex@latest\` then restart relay-mcp.`);
-    }
-    try {
-        await execFileAsync(codexBin, ["login", "status"]);
-    }
-    catch {
-        failures.push("Error: Codex not authenticated.\nFix: run `codex login` then restart relay-mcp.");
-    }
-    if (failures.length > 0) {
-        process.stderr.write(failures.join("\n\n") + "\n");
-        process.exit(1);
+    const codexDiagnostic = await diagnoseCodexWorker();
+    if (!codexDiagnostic.available) {
+        process.stderr.write(`Error: ${codexDiagnostic.reason}\nFix: ${codexDiagnostic.remediation}\n` +
+            "Tip: run the `check_workers` MCP tool for a structured readiness report.\n");
+        return;
     }
     if (shouldPrintReadyBanner()) {
-        process.stderr.write(`relay-mcp ready\n  codex: ${codexVersion} ✓\n  auth: authenticated ✓\n  listening on stdio...\n`);
+        process.stderr.write(`relay-mcp ready\n  codex: ${codexDiagnostic.version} ✓\n  auth: authenticated ✓\n  listening on stdio...\n`);
     }
 }

package/dist/telemetry/run-event.js

@@ -0,0 +1,10 @@
+import { appendFileSync } from "node:fs";
+export const RELAY_EVENTS_LOG = "/tmp/relay-mcp-events.jsonl";
+export function writeRunEvent(event, logPath = RELAY_EVENTS_LOG) {
+    try {
+        appendFileSync(logPath, JSON.stringify(event) + "\n");
+    }
+    catch {
+        // Best-effort — never crash the server over a log write.
+    }
+}

package/dist/tools/check_workers.js

@@ -0,0 +1,15 @@
+import { diagnoseCodexWorker } from "../workers/diagnostics.js";
+export async function handleCheckWorkers() {
+    const codexDiagRaw = await diagnoseCodexWorker();
+    const codexDiag = {
+        worker: codexDiagRaw.worker,
+        available: codexDiagRaw.available,
+        reason: codexDiagRaw.reason,
+        remediation: codexDiagRaw.remediation,
+    };
+    const result = {
+        workers: [codexDiag],
+        all_available: codexDiag.available,
+    };
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+}

package/dist/tools/delegate.js

@@ -1,13 +1,42 @@
 import * as path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { createWriteStream, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { DEFAULT_TIMEOUT_MS, TOKEN_HARD_CAP, TOKEN_WARN_THRESHOLD } from "../config/constants.js";
 import { makeError } from "../errors.js";
 import { getWorkdirMutex } from "../concurrency/index.js";
 import { diffSnapshots, takeSnapshot } from "../git/snapshot.js";
-import { runCodexWorker } from "../workers/codex.js";
+import { getRunner } from "../workers/registry.js";
+import { writeRunEvent } from "../telemetry/run-event.js";
 /** Canonical workdir normalization - used by mutex key, snapshot, and worker. */
 function normalizeWorkdir(rawWorkdir) {
     return path.resolve(rawWorkdir);
 }
+function computeLogPath(workdir) {
+    const hash = createHash("sha1").update(workdir).digest("hex").slice(0, 8);
+    return `/tmp/relay-mcp-${hash}.log`;
+}
+/**
+ * Resolve AGENTS.md from workdir upward to filesystem root.
+ * Nearest non-empty file wins.
+ */
+export function readNearestAgentsMd(workdir) {
+    let current = path.resolve(workdir);
+    while (true) {
+        try {
+            const content = readFileSync(join(current, "AGENTS.md"), "utf8").trim();
+            if (content.length > 0)
+                return content;
+        }
+        catch {
+            // Continue traversing to parent.
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
 function buildDelegateMeta(params) {
     return {
         duration_ms: params.duration_ms,
@@ -16,6 +45,11 @@ function buildDelegateMeta(params) {
         model: params.model ?? null,
         token_estimate: params.token_estimate,
         exit_code: params.exit_code,
+        log_file: params.log_file,
+        run_id: params.run_id,
+        provider: params.provider,
+        spawn_time_ms: params.spawn_time_ms,
+        token_usage: params.token_usage,
     };
 }
 function toMcpResult(response) {
@@ -43,52 +77,186 @@ export function applyTruncation(output, warnings) {
         tokenEstimate,
     };
 }
+function normalizeThrownError(err) {
+    if (err instanceof Error && err.message.startsWith("PROVIDER_NOT_CONFIGURED:")) {
+        return makeError("PROVIDER_NOT_CONFIGURED", err.message, false);
+    }
+    return makeError("UNKNOWN", `Unexpected worker error: ${String(err)}`, false);
+}
 export async function handleDelegate(args) {
-    const { task, workdir: rawWorkdir, context, timeout_ms, model } = args;
+    const { task, workdir: rawWorkdir, context, timeout_ms, model, provider = "codex" } = args;
+    const modelOverride = model?.trim() ? model.trim() : undefined;
+    const run_id = randomUUID();
+    const queued_at = Date.now();
     const workdir = normalizeWorkdir(rawWorkdir);
-    const finalTask = context ? `${context}\n\n${task}` : task;
-    const preSnapshot = await takeSnapshot(workdir);
-    const release = await getWorkdirMutex(workdir).acquire();
+    const agentsContext = readNearestAgentsMd(workdir);
+    const parts = [];
+    if (agentsContext)
+        parts.push(agentsContext);
+    if (context)
+        parts.push(context);
+    parts.push(task);
+    const finalTask = parts.join("\n\n");
+    const knownProviders = new Set(["codex", "openrouter", "lmstudio"]);
+    const isKnownProvider = knownProviders.has(provider);
+    const isAgenticProvider = provider === "codex";
+    const logPath = computeLogPath(workdir);
+    if (!isKnownProvider) {
+        const response = {
+            status: "error",
+            output: "",
+            files_changed: [],
+            meta: buildDelegateMeta({
+                duration_ms: 0,
+                truncated: false,
+                warnings: [],
+                model: modelOverride,
+                token_estimate: 0,
+                exit_code: null,
+                log_file: logPath,
+                run_id,
+                provider,
+                spawn_time_ms: 0,
+                token_usage: null,
+            }),
+            error: makeError("PROVIDER_NOT_CONFIGURED", `PROVIDER_NOT_CONFIGURED: unknown provider "${provider}"`, false),
+        };
+        return toMcpResult(response);
+    }
+    if (!isAgenticProvider && !modelOverride) {
+        const response = {
+            status: "error",
+            output: "",
+            files_changed: [],
+            meta: buildDelegateMeta({
+                duration_ms: 0,
+                truncated: false,
+                warnings: [],
+                model: modelOverride,
+                token_estimate: 0,
+                exit_code: null,
+                log_file: logPath,
+                run_id,
+                provider,
+                spawn_time_ms: 0,
+                token_usage: null,
+            }),
+            error: makeError("INVALID_ARGS", `model is required when provider is "${provider}". Pass an explicit provider model ID.`, false),
+        };
+        return toMcpResult(response);
+    }
+    writeRunEvent({ run_id, provider, model: modelOverride ?? null, workdir, status: "queued", queued_at });
+    let release = null;
+    let preSnapshot = null;
+    if (isAgenticProvider) {
+        release = await getWorkdirMutex(workdir).acquire();
+        preSnapshot = await takeSnapshot(workdir);
+    }
+    const logStream = createWriteStream(logPath, { flags: "a" });
+    logStream.on("error", () => {
+        /* swallow write errors - log is best-effort */
+    });
     let workerResult;
+    let postSnapshot = null;
+    const started_at = Date.now();
+    const spawn_time_ms = started_at - queued_at;
+    writeRunEvent({
+        run_id,
+        provider,
+        model: modelOverride ?? null,
+        workdir,
+        status: "running",
+        queued_at,
+        started_at,
+        spawn_time_ms,
+    });
     try {
+        const runner = getRunner(provider);
         const workerTask = {
             task: finalTask,
             workdir,
             timeout_ms: timeout_ms ?? DEFAULT_TIMEOUT_MS,
-            model,
+            model: modelOverride,
+            logStream,
+            onStderr: (text) => {
+                process.stderr.write(text);
+                logStream.write(text);
+            },
+            run_id,
+            provider,
         };
-        workerResult = await runCodexWorker(workerTask);
+        workerResult = await runner.run(workerTask);
+        if (isAgenticProvider) {
+            postSnapshot = await takeSnapshot(workdir);
+        }
     }
     catch (err) {
+        logStream.end();
+        const finished_at = Date.now();
+        const normalizedError = normalizeThrownError(err);
+        writeRunEvent({
+            run_id,
+            provider,
+            model: modelOverride ?? null,
+            workdir,
+            status: "error",
+            queued_at,
+            started_at,
+            finished_at,
+            duration_ms: finished_at - started_at,
+            spawn_time_ms,
+            error_code: normalizedError.code,
+        });
         const response = {
             status: "error",
             output: "",
             files_changed: [],
             meta: buildDelegateMeta({
-                duration_ms: 0,
+                duration_ms: finished_at - started_at,
                 truncated: false,
                 warnings: [],
-                model,
+                model: modelOverride,
                 token_estimate: 0,
                 exit_code: null,
+                log_file: logPath,
+                run_id,
+                provider,
+                spawn_time_ms,
+                token_usage: null,
             }),
-            error: makeError("UNKNOWN", `Unexpected worker error: ${String(err)}`, false),
+            error: normalizedError,
         };
         return toMcpResult(response);
     }
     finally {
-        release();
+        release?.();
     }
-    const postSnapshot = await takeSnapshot(workdir);
-    const filesChanged = diffSnapshots(preSnapshot, postSnapshot);
+    logStream.end();
+    const finished_at = Date.now();
+    const duration_ms = finished_at - started_at;
+    const filesChanged = isAgenticProvider ? diffSnapshots(preSnapshot, postSnapshot) : [];
     const warnings = [];
-    if (preSnapshot === null) {
+    if (isAgenticProvider && preSnapshot === null) {
         warnings.push("workdir is not a git repository - files_changed tracking unavailable");
     }
-    else if (filesChanged.length === 0 && workerResult.status === "success") {
+    else if (isAgenticProvider && filesChanged.length === 0 && workerResult.status === "success") {
         warnings.push("No files were modified by Codex");
     }
     const { output, truncated, tokenEstimate } = applyTruncation(workerResult.output, warnings);
+    const eventStatus = workerResult.status === "success"
+        ? "success"
+        : workerResult.status === "timeout"
+            ? "timeout"
+            : "error";
+    writeRunEvent({
+        run_id, provider, model: modelOverride ?? null, workdir, status: eventStatus,
+        queued_at, started_at, finished_at, duration_ms,
+        spawn_time_ms,
+        output_size_chars: output.length,
+        exit_code: workerResult.exit_code,
+        token_usage: workerResult.token_usage ?? null,
+        ...(workerResult.error ? { error_code: workerResult.error.code } : {}),
+    });
     const response = {
         status: workerResult.status,
         output,
@@ -97,9 +265,14 @@ export async function handleDelegate(args) {
             duration_ms: workerResult.duration_ms,
             truncated,
             warnings,
-            model,
+            model: modelOverride,
             token_estimate: tokenEstimate,
             exit_code: workerResult.exit_code,
+            log_file: logPath,
+            run_id,
+            provider,
+            spawn_time_ms,
+            token_usage: workerResult.token_usage ?? null,
         }),
         ...(workerResult.error ? { error: workerResult.error } : {}),
     };

package/dist/utils/version.js

@@ -0,0 +1,18 @@
+/**
+ * Returns true when `version` is lower than `min`.
+ * Accepted version format: MAJOR.MINOR.PATCH (optionally prefixed/suffixed).
+ */
+export function isVersionBelow(version, min) {
+    const match = version.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return true;
+    const [, maj, min_, pat] = match.map(Number);
+    if (maj !== min[0])
+        return maj < min[0];
+    if (min_ !== min[1])
+        return min_ < min[1];
+    return pat < min[2];
+}
+export function formatVersionTriplet(version) {
+    return version.join(".");
+}

package/dist/workers/codex.js

@@ -47,11 +47,17 @@ export async function runCodexWorker(task) {
             const message = parseCodexLine(line);
             if (message) {
                 agentMessages.push(message);
+                task.logStream?.write(message + "\n");
             }
         }
     });
     child.stderr?.on("data", (chunk) => {
-        process.stderr.write(chunk);
+        const text = chunk.toString("utf8");
+        if (task.onStderr) {
+            task.onStderr(text);
+            return;
+        }
+        process.stderr.write(text);
     });
     let timedOut = false;
     const timeoutHandle = setTimeout(() => {
@@ -76,6 +82,7 @@ export async function runCodexWorker(task) {
                 const message = parseCodexLine(stdoutBuf);
                 if (message) {
                     agentMessages.push(message);
+                    task.logStream?.write(message + "\n");
                 }
             }
             const duration_ms = Date.now() - startTime;
@@ -123,3 +130,8 @@ export async function runCodexWorker(task) {
         });
     });
 }
+export class CodexRunner {
+    run(task) {
+        return runCodexWorker(task);
+    }
+}

package/dist/workers/diagnostics.js

@@ -0,0 +1,56 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { MIN_CODEX_VERSION } from "../config/constants.js";
+import { getCodexBin } from "../config/runtime.js";
+import { formatVersionTriplet, isVersionBelow } from "../utils/version.js";
+const execFileAsync = promisify(execFile);
+export async function diagnoseCodexWorker() {
+    const codexBin = getCodexBin();
+    const configuredPath = process.env.RELAY_CODEX_PATH?.trim();
+    const binaryHint = configuredPath
+        ? `RELAY_CODEX_PATH=${configuredPath}`
+        : "PATH (default `codex` binary)";
+    const minVersion = formatVersionTriplet(MIN_CODEX_VERSION);
+    let version = "";
+    try {
+        const { stdout } = await execFileAsync(codexBin, ["--version"]);
+        version = stdout.trim();
+    }
+    catch {
+        return {
+            worker: "codex",
+            available: false,
+            version: null,
+            reason: `Codex binary not found via ${binaryHint}`,
+            remediation: "run: npm install -g @openai/codex  OR  set RELAY_CODEX_PATH=/full/path/to/codex in your MCP config",
+        };
+    }
+    if (isVersionBelow(version, MIN_CODEX_VERSION)) {
+        return {
+            worker: "codex",
+            available: false,
+            version,
+            reason: `Codex ${version} is below minimum ${minVersion}`,
+            remediation: "run: npm install -g @openai/codex@latest  then restart relay-mcp",
+        };
+    }
+    try {
+        await execFileAsync(codexBin, ["login", "status"]);
+    }
+    catch {
+        return {
+            worker: "codex",
+            available: false,
+            version,
+            reason: `Codex ${version} found but not authenticated`,
+            remediation: "run: codex login  then restart relay-mcp",
+        };
+    }
+    return {
+        worker: "codex",
+        available: true,
+        version,
+        reason: `${version} authenticated`,
+        remediation: "",
+    };
+}

package/dist/workers/lmstudio.js

@@ -0,0 +1,84 @@
+import { makeError } from "../errors.js";
+import { getLmStudioEndpoint, getLmStudioApiKey } from "../config/providers.js";
+export function parseLmStudioResponse(body) {
+    const choices = body["choices"] ?? [];
+    const output = choices[0]?.message?.content ?? "";
+    const usage = body["usage"];
+    return { output, token_usage: usage?.["completion_tokens"] ?? null };
+}
+export class LmStudioRunner {
+    async run(task) {
+        const model = task.model?.trim();
+        if (!model) {
+            return {
+                status: "error",
+                output: "",
+                duration_ms: 0,
+                exit_code: null,
+                error: makeError("INVALID_ARGS", "model is required when provider is \"lmstudio\".", false),
+            };
+        }
+        const endpoint = getLmStudioEndpoint();
+        const apiKey = getLmStudioApiKey();
+        const startTime = Date.now();
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), task.timeout_ms);
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (apiKey) {
+            headers["Authorization"] = `Bearer ${apiKey}`;
+        }
+        const requestBody = {
+            model,
+            messages: [{ role: "user", content: task.task }],
+        };
+        let res;
+        try {
+            res = await fetch(`${endpoint}/v1/chat/completions`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(requestBody),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            clearTimeout(timeout);
+            const duration_ms = Date.now() - startTime;
+            if (err.name === "AbortError") {
+                return {
+                    status: "timeout",
+                    output: "",
+                    duration_ms,
+                    exit_code: null,
+                    error: makeError("TIMEOUT", `LM Studio timed out after ${task.timeout_ms}ms`, true),
+                };
+            }
+            return {
+                status: "error",
+                output: "",
+                duration_ms,
+                exit_code: null,
+                error: makeError("PROVIDER_ERROR", `LM Studio fetch failed: ${String(err)}. Is it running at ${endpoint}?`, true),
+            };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        const duration_ms = Date.now() - startTime;
+        if (!res.ok) {
+            const body = await res.text();
+            return {
+                status: "error",
+                output: "",
+                duration_ms,
+                exit_code: res.status,
+                error: makeError("PROVIDER_ERROR", `LM Studio returned ${res.status}: ${body}`, res.status >= 500),
+            };
+        }
+        const body = (await res.json());
+        const { output, token_usage } = parseLmStudioResponse(body);
+        task.logStream?.write(output + "\n");
+        return { status: "success", output, duration_ms, exit_code: 0, token_usage };
+    }
+}

package/dist/workers/openrouter.js

@@ -0,0 +1,88 @@
+import { makeError } from "../errors.js";
+import { getOpenRouterApiKey } from "../config/providers.js";
+export function parseOpenRouterResponse(body) {
+    const choices = body["choices"] ?? [];
+    const output = choices[0]?.message?.content ?? "";
+    const usage = body["usage"];
+    return { output, token_usage: usage?.["completion_tokens"] ?? null };
+}
+export class OpenRouterRunner {
+    async run(task) {
+        const model = task.model?.trim();
+        if (!model) {
+            return {
+                status: "error",
+                output: "",
+                duration_ms: 0,
+                exit_code: null,
+                error: makeError("INVALID_ARGS", "model is required when provider is \"openrouter\".", false),
+            };
+        }
+        const apiKey = getOpenRouterApiKey();
+        if (!apiKey) {
+            return {
+                status: "error",
+                output: "",
+                duration_ms: 0,
+                exit_code: null,
+                error: makeError("PROVIDER_NOT_CONFIGURED", "OPENROUTER_API_KEY is not set. Add it to your MCP config env.", false),
+            };
+        }
+        const startTime = Date.now();
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), task.timeout_ms);
+        let res;
+        try {
+            res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    model,
+                    messages: [{ role: "user", content: task.task }],
+                }),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            clearTimeout(timeout);
+            const duration_ms = Date.now() - startTime;
+            if (err.name === "AbortError") {
+                return {
+                    status: "timeout",
+                    output: "",
+                    duration_ms,
+                    exit_code: null,
+                    error: makeError("TIMEOUT", `OpenRouter timed out after ${task.timeout_ms}ms`, true),
+                };
+            }
+            return {
+                status: "error",
+                output: "",
+                duration_ms,
+                exit_code: null,
+                error: makeError("PROVIDER_ERROR", `OpenRouter fetch failed: ${String(err)}`, true),
+            };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        const duration_ms = Date.now() - startTime;
+        if (!res.ok) {
+            const body = await res.text();
+            return {
+                status: "error",
+                output: "",
+                duration_ms,
+                exit_code: res.status,
+                error: makeError("PROVIDER_ERROR", `OpenRouter returned ${res.status}: ${body}`, res.status >= 500),
+            };
+        }
+        const body = (await res.json());
+        const { output, token_usage } = parseOpenRouterResponse(body);
+        task.logStream?.write(output + "\n");
+        return { status: "success", output, duration_ms, exit_code: 0, token_usage };
+    }
+}

package/dist/workers/registry.js

@@ -0,0 +1,15 @@
+import { CodexRunner } from "./codex.js";
+import { OpenRouterRunner } from "./openrouter.js";
+import { LmStudioRunner } from "./lmstudio.js";
+const runners = {
+    codex: new CodexRunner(),
+    openrouter: new OpenRouterRunner(),
+    lmstudio: new LmStudioRunner(),
+};
+export function getRunner(provider) {
+    const runner = runners[provider];
+    if (!runner) {
+        throw new Error(`PROVIDER_NOT_CONFIGURED: unknown provider "${provider}"`);
+    }
+    return runner;
+}

package/dist/workers/runner.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sghanavati/relay-mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "MCP server that lets Claude Code delegate coding tasks to Codex",
   "type": "module",
   "bin": {