@retasc/cli 1.29.0 → 1.31.0

package/dist/proxy.js

@@ -16,6 +16,7 @@ import { resolveConn } from "./lib/keystore.js";
 import { toolResult as parseTool } from "./lib/toolresult.js";
 import { mintSessionKey, appendFallbackNotice } from "./lib/session.js";
 import { attachRoot, isLocalAttachCall, mergeAttachTool, resolveAttachPath, uploadFailureMessage, uploadUrlWith, } from "./lib/attachFile.js";
+import { MAX_FETCH_BYTES, downloadFailureMessage, existingDownload, isLocalFetchCall, mergeFetchTool, resolveDownloadTarget, writeDownloadedFile, } from "./lib/fetchFile.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).
@@ -260,6 +261,132 @@ async function handleLocalAttach(msg) {
         return replyToolResult(msg.id, `upload failed: ${String(e?.message ?? e)}`, true);
     }
 }
+/**
+ * Serve `get_attachment_file` LOCALLY (RTSC-681): the agent names an attachment id, we fetch
+ * the bytes with the key we already hold and write them to a file the agent can open. The
+ * mirror of handleLocalAttach above, and the other half of the same fix — attachments were a
+ * one-way street, and the way back required a credential the model is told it must not go
+ * looking for.
+ *
+ * The metadata comes from the server rather than being assumed here, for the same reason the
+ * upload asks for its URL: the auth check, the project boundary and "is there even a file"
+ * stay server-authoritative, so this side holds no policy it could get wrong. Only then do we
+ * spend a download.
+ *
+ * Every write is logged to stderr with its resolved path. A proxy-side write bypasses the
+ * harness's own file-write prompt, so the MCP log is where a human can see what appeared on
+ * their disk on their behalf.
+ */
+async function handleLocalFetch(msg) {
+    const args = (msg.params?.arguments ?? {});
+    const attachment = typeof args.attachment === "string" ? args.attachment.trim() : "";
+    if (!attachment) {
+        return replyToolResult(msg.id, "attachment is required (an attachment id from list_attachments)", true);
+    }
+    // Ask the server what this is. Doubles as the auth + existence + project-boundary check, so
+    // a bad id or a foreign project fails before we write anything.
+    let meta;
+    try {
+        meta = toolResult(await postRemote({
+            jsonrpc: "2.0",
+            id: hbSeq--,
+            method: "tools/call",
+            params: { name: "get_attachment", arguments: { attachment } },
+        }), "get_attachment");
+    }
+    catch (e) {
+        return replyToolResult(msg.id, `could not reach Retasc: ${String(e?.message ?? e)}`, true);
+    }
+    const url = typeof meta?.url === "string" ? meta.url : "";
+    if (!url) {
+        // Relay what the server said rather than a generic failure: it is usually NOT_FOUND for
+        // this id, and that is the sentence the agent needs to see.
+        const detail = typeof meta === "string" ? meta : JSON.stringify(meta ?? null);
+        return replyToolResult(msg.id, `could not read attachment ${attachment}: ${detail}`, true);
+    }
+    // Whether there are bytes is the SERVER's answer, never inferred from the URL. An earlier
+    // draft fell back to matching the download path in the URL when `hasFile` was absent, which
+    // is a credential leak: a LINK attachment's URL is arbitrary text any org member can write,
+    // so `https://evil.example/attachments/download?x=1` would have matched and this fetch would
+    // have carried our Bearer token to their host. A server too old to answer gets an error that
+    // names the fix, which is the safe direction to fail.
+    if (meta.hasFile !== true) {
+        const why = meta.hasFile === false
+            ? `attachment ${attachment} is a link, not an uploaded file — there are no bytes to download. ` +
+                `Fetch it yourself if you can reach it: ${url}`
+            : `this Retasc deployment is too old to serve get_attachment_file (its get_attachment does ` +
+                `not report whether an attachment has a file). Ask your human to update the backend.`;
+        return replyToolResult(msg.id, why, true);
+    }
+    // Belt and braces on the URL the server handed back: only ever send the credential to the
+    // endpoint this feature is about, over http(s), never to a `file:`/`data:` scheme or some
+    // other path that a future server-side bug might emit here.
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return replyToolResult(msg.id, `could not read attachment ${attachment}: the server returned an unusable URL`, true);
+    }
+    // `endsWith`, not `===`: a deployment whose site URL carries a path prefix serves the same
+    // endpoint under it, and rejecting that would break a legitimate install to catch nothing.
+    if (!/^https?:$/.test(parsed.protocol) || !parsed.pathname.endsWith("/attachments/download")) {
+        log(`refused download of ${attachment}: unexpected download URL ${parsed.origin}${parsed.pathname}`);
+        return replyToolResult(msg.id, `refusing to download ${attachment}: the server returned an unexpected download URL.`, true);
+    }
+    const declared = typeof meta.bytes === "number" ? meta.bytes : undefined;
+    if (declared !== undefined && declared > MAX_FETCH_BYTES) {
+        return replyToolResult(msg.id, `attachment ${attachment} is ${declared} bytes, over the ${MAX_FETCH_BYTES}-byte limit`, true);
+    }
+    const target = resolveDownloadTarget(ATTACH_ROOT, attachment, meta.filename ?? meta.title);
+    if (!target.ok) {
+        log(`refused download of ${attachment}: ${target.error}`);
+        return replyToolResult(msg.id, target.error, true);
+    }
+    const describe = (bytes, cached) => JSON.stringify({
+        attachment,
+        issue: meta.issue,
+        path: target.path,
+        filename: target.filename,
+        bytes,
+        contentType: meta.contentType,
+        obsolete: meta.obsolete ?? false,
+        cached,
+        note: "The file is on disk — read it with your normal file tools. Copy it elsewhere yourself if you want to keep it; this directory is git-ignored and is not cleaned up for you.",
+    }, null, 2);
+    // An attachment id maps to immutable bytes, so a file already sitting at this exact path IS
+    // this attachment — hand it back rather than paying for the same egress twice.
+    const existing = existingDownload(target.path);
+    if (existing && "symlink" in existing) {
+        const error = `refusing to use ${target.path}: it is a symlink, not a downloaded file. Remove it and try again.`;
+        log(error);
+        return replyToolResult(msg.id, error, true);
+    }
+    if (existing) {
+        log(`${attachment} already downloaded → ${target.path}`);
+        return replyToolResult(msg.id, describe(existing.size, true), false);
+    }
+    try {
+        const res = await fetch(url, { headers: { Authorization: `Bearer ${activeKey}` } });
+        if (!res.ok) {
+            const body = await res.text();
+            log(`download of ${attachment} failed: HTTP ${res.status}`);
+            return replyToolResult(msg.id, downloadFailureMessage(res.status, body), true);
+        }
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        // The declared size was a claim; this is what actually arrived. Check it before it lands
+        // on disk — a response is not bounded by what the metadata said it would be.
+        if (bytes.byteLength > MAX_FETCH_BYTES) {
+            return replyToolResult(msg.id, `download aborted: ${bytes.byteLength} bytes exceeds the ${MAX_FETCH_BYTES}-byte limit`, true);
+        }
+        writeDownloadedFile(target, bytes, ATTACH_ROOT);
+        log(`downloaded ${attachment} (${bytes.byteLength} bytes) → ${target.path}`);
+        return replyToolResult(msg.id, describe(bytes.byteLength, false), false);
+    }
+    catch (e) {
+        return replyToolResult(msg.id, `download failed: ${String(e?.message ?? e)}`, true);
+    }
+}
 async function handleLine(line) {
     const trimmed = line.trim();
     if (!trimmed)
@@ -276,6 +403,11 @@ async function handleLine(line) {
     // tool called with `contentBase64`, the server's own variant) goes remote untouched.
     if (isLocalAttachCall(msg))
         return await handleLocalAttach(msg);
+    // RTSC-681: the read counterpart. Whenever a proxy is present, downloading to disk beats
+    // the server's inline variant on every axis (no size ceiling, no bytes in the model's
+    // context), so every call to the tool is served here rather than forwarded.
+    if (isLocalFetchCall(msg))
+        return await handleLocalFetch(msg);
     let resp;
     try {
         resp = await postRemote(msg);
@@ -296,8 +428,13 @@ async function handleLine(line) {
     // tell the agent which shape this environment can actually serve.
     if (msg.method === "tools/list" && resp && typeof resp === "object") {
         const result = resp.result;
-        if (result && Array.isArray(result.tools))
+        if (result && Array.isArray(result.tools)) {
             result.tools = mergeAttachTool(result.tools, ATTACH_ROOT);
+            // RTSC-681: same override for the read half — one name, the shape this environment can
+            // actually serve, decided at the only moment we get to tell the agent (tools/list is
+            // fetched once, at startup).
+            result.tools = mergeFetchTool(result.tools, ATTACH_ROOT);
+        }
     }
     // Watch tools/call traffic for claims/releases (request args + result), and
     // flag the workspace-key fallback on whoami so the AGENT sees the degraded

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.29.0",
+  "version": "1.31.0",
   "description": "Retasc CLI \u2014 the issue tracker AI agents pull work from. Sign in with GitHub or Google, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {