@retasc/cli 1.0.0

package/dist/proxy.js

@@ -0,0 +1,147 @@
+// Liveness watchdog proxy (RTSC-44). A stdio MCP server the harness (Claude Code,
+// Codex, OpenCode, …) spawns. It transparently forwards every JSON-RPC message to
+// the remote Retasc MCP over HTTP and — by watching claim tokens in the responses —
+// keeps claimed issues' leases alive with out-of-band `heartbeat` calls. The LLM
+// never heartbeats. Fail-safe: if this process dies, heartbeats stop and the server
+// reclaims the lease (the correct default) — a broken watchdog is never worse than
+// no watchdog. Self-enforcing: no proxy → no Retasc tools → can't orphan a lease.
+import { createInterface } from "node:readline";
+import { hostname } from "node:os";
+import { applyObservation, heartbeatRequest, isClaimLost, } from "./lib/watchdog.js";
+const MCP_URL = process.env.RETASC_MCP_URL || "https://mcp.retasc.com/mcp";
+const KEY = process.env.RETASC_MCP_KEY || "";
+const HEARTBEAT_MS = Number(process.env.RETASC_HEARTBEAT_MS) || 10 * 60 * 1000;
+const leases = new Map();
+let hbSeq = -1; // out-of-band heartbeat ids are negative — never collide with the harness's
+// Per-session key (RTSC-50): starts as the workspace key; on startup we mint a
+// session key and switch to it so this session is distinguishable from others.
+let activeKey = KEY;
+// stderr only: stdout is the MCP channel and must carry ONLY protocol messages.
+function log(msg) {
+    process.stderr.write(`[retasc-watchdog] ${msg}\n`);
+}
+async function postRemote(body) {
+    const res = await fetch(MCP_URL, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${activeKey}`,
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    return text ? JSON.parse(text) : null;
+}
+/**
+ * Auto-adopt a per-session key (RTSC-50). Mint one bound to our identity and use
+ * it for the rest of the session, so concurrent sessions of the same agent are
+ * distinguishable. Fail-soft: if minting is unavailable (older server, error),
+ * keep using the workspace key — no worse than before.
+ */
+async function adoptSessionKey() {
+    if (!KEY)
+        return;
+    const label = process.env.RETASC_SESSION_LABEL || `${hostname()}#${process.pid}`;
+    try {
+        const resp = await postRemote({
+            jsonrpc: "2.0",
+            id: -1000,
+            method: "tools/call",
+            params: { name: "mint_session_key", arguments: { label } },
+        });
+        const r = toolResult(resp);
+        if (r && typeof r === "object" && typeof r.key === "string") {
+            activeKey = r.key; // switch to the session key
+            log(`adopted session key "${r.session ?? label}"`);
+        }
+        else {
+            log("mint_session_key unavailable — using the workspace key");
+        }
+    }
+    catch (e) {
+        log(`session-key mint failed (${String(e?.message ?? e)}) — using the workspace key`);
+    }
+}
+// The tool result payload — the JSON inside result.content[0].text — or the raw result.
+function toolResult(resp) {
+    try {
+        const t = resp?.result?.content?.[0]?.text;
+        return t ? JSON.parse(t) : resp?.result;
+    }
+    catch {
+        return resp?.result;
+    }
+}
+async function handleLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return;
+    let msg;
+    try {
+        msg = JSON.parse(trimmed);
+    }
+    catch {
+        return; // not a JSON-RPC message — ignore
+    }
+    let resp;
+    try {
+        resp = await postRemote(msg);
+    }
+    catch (e) {
+        // Forwarding failed: return a JSON-RPC error so the harness doesn't hang.
+        if (msg.id !== undefined) {
+            process.stdout.write(JSON.stringify({
+                jsonrpc: "2.0",
+                id: msg.id,
+                error: { code: -32000, message: `retasc proxy forward failed: ${String(e?.message ?? e)}` },
+            }) + "\n");
+        }
+        return;
+    }
+    // Watch tools/call traffic for claims/releases (request args + result).
+    if (msg.method === "tools/call" && resp) {
+        applyObservation(leases, {
+            toolName: msg.params?.name,
+            args: msg.params?.arguments,
+            result: toolResult(resp),
+        });
+    }
+    // Relay the response (requests have an id; notifications don't).
+    if (resp != null && msg.id !== undefined) {
+        process.stdout.write(JSON.stringify(resp) + "\n");
+    }
+}
+async function heartbeatAll() {
+    for (const [issueId, token] of [...leases]) {
+        try {
+            const resp = await postRemote(heartbeatRequest(hbSeq--, issueId, token));
+            if (isClaimLost(toolResult(resp))) {
+                leases.delete(issueId);
+                log(`lease for ${issueId} is gone — stopped tracking`);
+            }
+        }
+        catch (e) {
+            log(`heartbeat for ${issueId} failed: ${String(e?.message ?? e)}`);
+        }
+    }
+}
+/** Run the stdio proxy. Started by the harness; lives as long as the session. */
+export async function runProxy() {
+    if (!KEY)
+        log("warning: RETASC_MCP_KEY is empty — forwarded requests will be unauthorized");
+    // Adopt a per-session key BEFORE serving traffic, so even the first claim is
+    // attributed to this session. stdin buffers in the OS pipe meanwhile.
+    await adoptSessionKey();
+    const timer = setInterval(() => void heartbeatAll(), HEARTBEAT_MS);
+    timer.unref?.(); // the timer alone must not keep the process alive
+    const rl = createInterface({ input: process.stdin });
+    rl.on("line", (line) => void handleLine(line));
+    rl.on("close", () => {
+        // Don't hard-exit: let in-flight forwards finish and write their responses.
+        // With stdin closed and the timer unref'd, the process exits once the event
+        // loop drains. (In a real harness stdin stays open for the whole session.)
+        clearInterval(timer);
+    });
+    log(`up → ${MCP_URL} (heartbeat every ${Math.round(HEARTBEAT_MS / 60000)}m)`);
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@retasc/cli",
+  "version": "1.0.0",
+  "description": "Retasc CLI — sign in with GitHub, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
+  "type": "module",
+  "bin": {
+    "retasc": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "Retasc",
+  "homepage": "https://retasc.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Retasc/retasc.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/Retasc/retasc/issues"
+  },
+  "keywords": [
+    "retasc",
+    "mcp",
+    "issue-tracker",
+    "agent",
+    "ai-agents",
+    "work-queue",
+    "orchestration",
+    "claude-code",
+    "codex",
+    "cli"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "convex": "^1.41.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}