@retasc/cli 1.2.0 → 1.2.1

package/dist/lib/claim.js

@@ -5,6 +5,10 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { resolveConn } from "./keystore.js";
+// Tool-payload extraction lives in the shared tolerant parser (RTSC-143);
+// re-exported so existing importers of this module keep working.
+import { toolResult } from "./toolresult.js";
+export { toolResult };
 const DEFAULT_MCP_URL = "https://mcp.retasc.com/mcp";
 /**
  * Resolve the agent API key + MCP URL the same way the workspace's MCP wiring does,
@@ -84,16 +88,6 @@ export function parseClaimResult(result) {
     const title = typeof r.issue === "object" ? r.issue?.title : undefined;
     return { issueId, title, claimToken: r.claimToken };
 }
-/** The tool payload (JSON inside result.content[0].text), or the raw result. */
-export function toolResult(resp) {
-    try {
-        const t = resp?.result?.content?.[0]?.text;
-        return t ? JSON.parse(t) : resp?.result;
-    }
-    catch {
-        return resp?.result;
-    }
-}
 /**
  * Call one MCP tool over JSON-RPC with the agent key. Throws on transport errors
  * and on tool errors (isError) — surfacing the server's message (CLAIM_LOST,

package/dist/lib/session.js

@@ -0,0 +1,93 @@
+// Session-key adoption core (RTSC-143) — the mint call the proxy runs on startup
+// (RTSC-50), extracted here so the retry + failure behavior is unit-testable with
+// a stubbed fetch. Fail-soft stands: a broken mint must never take the MCP down —
+// but the fallback must be LOUD, because on the shared workspace key concurrent
+// sessions collapse into one server-side identity and the per-session claim fence
+// (RTSC-49/50) is silently inert.
+import { toolResult } from "./toolresult.js";
+// Out-of-band ids are negative so they never collide with the harness's (the
+// same convention as the proxy's heartbeat ids; announceBinding uses -1001).
+const MINT_RPC_ID = -1000;
+// The mint runs BEFORE the proxy serves `initialize`, so a hung server must not
+// stall startup past the harness's MCP timeout — that would turn "degraded
+// identity" into "no Retasc tools at all", the exact failure fail-soft exists
+// to avoid. Two attempts fit comfortably inside a ~30s harness budget.
+const MINT_TIMEOUT_MS = 5_000;
+const FALLBACK_CONSEQUENCE = "concurrent sessions will be indistinguishable to the server and the " +
+    "per-session claim fence is OFF for this session. Restart the session to retry.";
+/**
+ * Mint a per-session key, retrying once (a startup network blip must not demote
+ * the whole session's identity). Never throws. On double failure, emits an
+ * unmissable multi-line warning stating the consequence and returns {ok:false}
+ * so the caller can keep flagging the degraded state (e.g. on whoami).
+ */
+export async function mintSessionKey(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const warn = opts.warn ?? ((msg) => process.stderr.write(`[retasc] ${msg}\n`));
+    const retryDelayMs = opts.retryDelayMs ?? 500;
+    for (let attempt = 1; attempt <= 2; attempt++) {
+        try {
+            const res = await fetchImpl(opts.url, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${opts.key}`,
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: MINT_RPC_ID,
+                    method: "tools/call",
+                    params: { name: "mint_session_key", arguments: { label: opts.label } },
+                }),
+                signal: AbortSignal.timeout(MINT_TIMEOUT_MS),
+            });
+            const text = await res.text();
+            // A non-2xx (revoked key → 401, server error → 5xx) must not masquerade
+            // as "no key in response" — surface the status so a dead key is obvious.
+            if (!res.ok) {
+                const snippet = text ? `: ${text.slice(0, 120).replace(/\s+/g, " ").trim()}` : "";
+                warn(`mint_session_key attempt ${attempt} failed (HTTP ${res.status})${snippet}`);
+            }
+            else {
+                const r = toolResult(text ? JSON.parse(text) : null, warn);
+                if (r && typeof r === "object" && typeof r.key === "string") {
+                    return { ok: true, key: r.key, session: r.session };
+                }
+                warn(`mint_session_key attempt ${attempt} returned no key`);
+            }
+        }
+        catch (e) {
+            warn(`mint_session_key attempt ${attempt} failed: ${String(e?.message ?? e)}`);
+        }
+        if (attempt === 1 && retryDelayMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+        }
+    }
+    warn("WARNING: could not mint a per-session key (retried once).");
+    warn(`WARNING: continuing on the SHARED WORKSPACE KEY — ${FALLBACK_CONSEQUENCE}`);
+    return { ok: false };
+}
+/**
+ * The warning content block appended to whoami responses when the session is
+ * running on the workspace-key fallback — so the AGENT sees the degraded state,
+ * not just whoever reads the MCP log files.
+ */
+export const MINT_FALLBACK_NOTICE = "⚠ Retasc watchdog: this session could not mint a per-session key and is using " +
+    `the shared workspace key — ${FALLBACK_CONSEQUENCE}`;
+/**
+ * Append MINT_FALLBACK_NOTICE to a whoami response when degraded. Defensive on
+ * purpose: anything unexpected about the shape (error response, missing/non-array
+ * content) leaves the response untouched — a malformed notice must never break
+ * the protocol stream this rides on.
+ */
+export function appendFallbackNotice(toolName, resp, degraded) {
+    if (!degraded || toolName !== "whoami")
+        return;
+    const result = resp?.result;
+    if (result?.isError)
+        return; // don't decorate an error response
+    if (Array.isArray(result?.content)) {
+        result.content.push({ type: "text", text: MINT_FALLBACK_NOTICE });
+    }
+}

package/dist/lib/toolresult.js

@@ -0,0 +1,94 @@
+// Tolerant MCP tool-result parsing (RTSC-143) — pure, shared by proxy.ts and
+// lib/claim.ts (previously two silent near-identical copies). The RTSC-91 footer
+// regression survived unnoticed because a payload of `{json}\n\n— footer` failed
+// JSON.parse and the parser silently handed back the raw result envelope —
+// downstream code (lease tracking, claim parsing) then quietly misbehaved. This
+// parser (a) recovers the JSON prefix when the text has trailing non-JSON, and
+// (b) says so, so a shape regression is visible in MCP logs instead of vanishing.
+/** Pure core: classify + extract the payload from a JSON-RPC tools/call response. */
+export function parseToolResult(resp) {
+    const result = resp?.result;
+    const text = result?.content?.[0]?.text;
+    if (typeof text !== "string" || !text)
+        return { kind: "raw", value: result };
+    try {
+        return { kind: "json", value: JSON.parse(text) };
+    }
+    catch {
+        /* fall through to prefix recovery */
+    }
+    // Never RECOVER from an error response: error text is prose that may embed
+    // JSON-looking fragments (issue ids, tokens), and a recovered fragment would
+    // flow into lease tracking as if the call had succeeded.
+    if (!result?.isError) {
+        const recovered = parseJsonPrefix(text);
+        if (recovered)
+            return { kind: "recovered", value: recovered.value };
+    }
+    return { kind: "raw", value: result, unparseable: true };
+}
+const MAX_PREFIX_ATTEMPTS = 16;
+/**
+ * "Strip trailing junk after the top-level JSON value". Fast path: JSON.parse
+ * errors name the offending position (V8/JSC), which for a value-plus-footer is
+ * exactly where the junk starts. Fallback: a bounded backward scan for the
+ * payload's closing `}`/`]`. Either way a candidate is only accepted when the
+ * discarded tail is NOT itself JSON-like — concatenated JSON values (NDJSON
+ * style) are a shape break where silently dropping the second value would be
+ * worse than the raw fallback.
+ */
+function parseJsonPrefix(text) {
+    if (!/^\s*[{[]/.test(text))
+        return undefined; // only object/array payloads
+    const accept = (end) => {
+        if (/^\s*[{[]/.test(text.slice(end)))
+            return undefined; // tail is more JSON — refuse
+        try {
+            return { value: JSON.parse(text.slice(0, end)) };
+        }
+        catch {
+            return undefined;
+        }
+    };
+    try {
+        JSON.parse(text);
+    }
+    catch (e) {
+        const m = /position\s+(\d+)/i.exec(String(e?.message ?? e));
+        if (m) {
+            const hit = accept(Number(m[1]));
+            if (hit)
+                return hit;
+        }
+    }
+    let end = text.length;
+    for (let attempt = 0; attempt < MAX_PREFIX_ATTEMPTS; attempt++) {
+        const close = Math.max(text.lastIndexOf("}", end - 1), text.lastIndexOf("]", end - 1));
+        if (close < 0)
+            return undefined;
+        const hit = accept(close + 1);
+        if (hit)
+            return hit;
+        end = close; // that candidate wasn't the payload's end — try the previous one
+    }
+    return undefined;
+}
+function warnStderr(msg) {
+    process.stderr.write(`[retasc] ${msg}\n`);
+}
+/**
+ * The tool payload (JSON inside result.content[0].text), or the raw result.
+ * Drop-in for the old silent copies, except a degraded parse now WARNS (stderr —
+ * stdout may be the MCP channel): callers that only care about the value keep
+ * their one-liner, and a server shape regression is at least visible in logs.
+ */
+export function toolResult(resp, warn = warnStderr) {
+    const p = parseToolResult(resp);
+    if (p.kind === "recovered") {
+        warn("tool result had trailing non-JSON text — recovered the leading JSON payload");
+    }
+    else if (p.unparseable) {
+        warn("tool result text is not JSON — falling back to the raw result envelope");
+    }
+    return p.value;
+}

package/dist/proxy.js

@@ -9,6 +9,8 @@ import { createInterface } from "node:readline";
 import { hostname } from "node:os";
 import { applyObservation, heartbeatRequest, isClaimLost, } from "./lib/watchdog.js";
 import { resolveConn } from "./lib/keystore.js";
+import { toolResult as parseTool } from "./lib/toolresult.js";
+import { mintSessionKey, appendFallbackNotice } from "./lib/session.js";
 // RTSC-92/98: resolve the workspace key via the SHARED resolver, so the proxy and
 // the direct commands (claim/tidy/done) can never diverge. The proxy carries its
 // binding in its own env (RETASC_MCP_KEY legacy, or RETASC_WORKSPACE → keystore).
@@ -21,6 +23,9 @@ let hbSeq = -1; // out-of-band heartbeat ids are negative — never collide with
 // 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;
+// Set when session-key minting failed and we fell back to the workspace key —
+// whoami responses get a warning block appended so the agent sees the degraded state.
+let sessionKeyFallback = false;
 // stderr only: stdout is the MCP channel and must carry ONLY protocol messages.
 function log(msg) {
     process.stderr.write(`[retasc-watchdog] ${msg}\n`);
@@ -42,30 +47,20 @@ async function postRemote(body) {
  * 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.
+ * keep using the workspace key — no worse than before — but LOUDLY (RTSC-143),
+ * because on the shared key the per-session claim fence is inert.
  */
 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");
-        }
+    const outcome = await mintSessionKey({ url: MCP_URL, key: KEY, label, warn: log });
+    if (outcome.ok) {
+        activeKey = outcome.key; // switch to the session key
+        log(`adopted session key "${outcome.session ?? label}"`);
     }
-    catch (e) {
-        log(`session-key mint failed (${String(e?.message ?? e)}) — using the workspace key`);
+    else {
+        sessionKeyFallback = true;
     }
 }
 /**
@@ -81,7 +76,7 @@ async function announceBinding() {
             method: "tools/call",
             params: { name: "whoami", arguments: {} },
         });
-        const r = toolResult(resp);
+        const r = toolResult(resp, "whoami");
         if (r?.org && r?.project) {
             log(`bound → org "${r.org.name}" / project ${r.project.prefix}`);
         }
@@ -90,15 +85,11 @@ async function announceBinding() {
         /* announcement is best-effort */
     }
 }
-// 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;
-    }
+// The tool result payload — shared tolerant parser (RTSC-143), warning through
+// our stderr logger (tool-labeled, so a busy MCP log names which call degraded)
+// when it had to recover a JSON prefix or fall back raw.
+function toolResult(resp, tool) {
+    return parseTool(resp, (msg) => log(tool ? `${tool}: ${msg}` : msg));
 }
 async function handleLine(line) {
     const trimmed = line.trim();
@@ -126,13 +117,16 @@ async function handleLine(line) {
         }
         return;
     }
-    // Watch tools/call traffic for claims/releases (request args + result).
+    // Watch tools/call traffic for claims/releases (request args + result), and
+    // flag the workspace-key fallback on whoami so the AGENT sees the degraded
+    // state (RTSC-143) — the startup stderr warning only reaches the MCP logs.
     if (msg.method === "tools/call" && resp) {
         applyObservation(leases, {
             toolName: msg.params?.name,
             args: msg.params?.arguments,
-            result: toolResult(resp),
+            result: toolResult(resp, msg.params?.name),
         });
+        appendFallbackNotice(msg.params?.name, resp, sessionKeyFallback);
     }
     // Relay the response (requests have an id; notifications don't).
     if (resp != null && msg.id !== undefined) {
@@ -143,7 +137,7 @@ async function heartbeatAll() {
     for (const [issueId, token] of [...leases]) {
         try {
             const resp = await postRemote(heartbeatRequest(hbSeq--, issueId, token));
-            if (isClaimLost(toolResult(resp))) {
+            if (isClaimLost(toolResult(resp, "heartbeat"))) {
                 leases.delete(issueId);
                 log(`lease for ${issueId} is gone — stopped tracking`);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "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": {