@retasc/cli 1.46.0 → 1.47.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.47.0 (2026-09-08)
+
+- **RTSC-864** — `retasc key mint` now prints every remote-key config block a hosted
+  agent can paste, including the TOML one that did not exist.
+
+  A key is shown once, and until now that was all `key mint` printed. Anyone wiring a
+  host that cannot run our proxy (a claude.ai connector, Codex Cloud, CI) had to invent
+  the config, and for two of the six harnesses it was not inventable: `tomlBlock` emitted
+  only the stdio proxy shape, so Codex and Grok users had nothing correct to paste at all.
+  The new `tomlHttpBlock` fills that in, and all three blocks now print next to the key
+  while it is still on the screen.
+
+  The two TOML dialects are separate on purpose, and the reason is the dangerous part.
+  Verified against both real binaries: Codex reads `[mcp_servers.retasc.http_headers]`
+  and Grok reads `[mcp_servers.retasc.headers]`, and each loads the other's file without
+  a warning while ignoring the header. The result is a server that reports itself
+  enabled and configured, and returns UNAUTHORIZED on the first tool call.
+
+  The blocks also say, next to themselves, that a key belongs in a user-scope config or
+  a platform secret store and never in a tracked `.mcp.json`, which the repo's pre-commit
+  hook refuses anyway. Where a container DOES have an environment, the proxy with
+  `RETASC_MCP_KEY` set is still the better door: it renews leases for you.
+
 ## 1.46.0 (2026-09-08)
 
 - **RTSC-855** — `retasc doctor` and `retasc setup` now say whether the **Retasc Agent

package/dist/commands/mcp.js

@@ -4,6 +4,9 @@ import { join } from "node:path";
 import { resolveLauncher, launcherNote, portableLauncher, } from "../lib/launcher.js";
 import { VERSION } from "../version.js";
 import { hasClaudeLocalPlaceholder } from "../lib/binding.js";
+// The TOML dialects live with the rest of the TOML knowledge (harness.ts), not here:
+// the same file has to keep Codex's and Grok's config shapes straight for the proxy form.
+import { tomlHttpBlock } from "../lib/harness.js";
 export const SERVER_NAME = "retasc";
 /** Normalize a user-supplied scope string. `user` (global) is refused and
  * downgraded to `local`, loudly — per-folder binding is the only right way. */
@@ -29,6 +32,47 @@ export function mcpServerEntry(url, key) {
 export function mcpConfigBlock(url, key) {
     return JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpServerEntry(url, key) } }, null, 2);
 }
+/**
+ * Every direct-form block, labelled with the harnesses that read it (RTSC-864).
+ *
+ * The direct form is for a host that cannot spawn our proxy at all, such as a claude.ai
+ * connector, Codex Cloud or a hosted OpenCode, where an HTTP URL and a bearer key is the
+ * only door. Two config languages and three dialects, because `tomlHttpBlock` documents
+ * that Codex and Grok silently ignore each other's header key.
+ *
+ * Printed by `key mint` in the same breath as the key itself, and NOT only when some
+ * install failed: the key is shown once, so every form a person might have to paste it
+ * into has to be on the screen while it is still readable. Sending them to a doc after
+ * the one credential they were given has scrolled away is how a key gets re-minted.
+ */
+export function directFormBlocks(url, key) {
+    return [
+        "Remote-key config, for a host that cannot run a local process",
+        "(claude.ai connectors, Codex Cloud, CI, any hosted agent):",
+        "",
+        "  JSON, for Claude Code, Cursor, OpenCode and Gemini CLI:",
+        "",
+        mcpConfigBlock(url, key),
+        "",
+        "  TOML, for Codex (~/.codex/config.toml):",
+        "",
+        tomlHttpBlock(url, key, "codex"),
+        "",
+        "  TOML, for Grok (~/.grok/config.toml):",
+        "",
+        tomlHttpBlock(url, key, "grok"),
+        "",
+        // The hook is not a style preference and the reason belongs next to the block that
+        // would trip it: a committed key is readable by everyone who ever clones the repo,
+        // and stays readable in git history after it is deleted.
+        "These blocks carry a live credential. Put them in the harness's own user-scope",
+        "config or the platform's secret store, never in a tracked `.mcp.json`. Retasc's own",
+        "repo refuses one at pre-commit, because a key committed once stays readable in git",
+        "history long after it is deleted.",
+        "Where the host DOES give you an environment, prefer the proxy with `RETASC_MCP_KEY`",
+        "set as a secret: it keeps your leases alive for you.",
+    ].join("\n");
+}
 /**
  * The stdio server entry that runs the liveness watchdog proxy (RTSC-44). The
  * harness spawns `retasc mcp-proxy`, which forwards to the remote MCP and keeps

package/dist/index.js

@@ -5,7 +5,7 @@ import { Command } from "commander";
 import { VERSION } from "./version.js";
 import { selfCommand, versionStamp } from "./lib/launcher.js";
 import { loadConfig, patchConfig, saveConfig, configPath, isLoggedIn } from "./config.js";
-import { installMcp, noteRuntimeIsALabel, normalizeScope } from "./commands/mcp.js";
+import { installMcp, noteRuntimeIsALabel, normalizeScope, directFormBlocks } from "./commands/mcp.js";
 import { runSetup, printSetup } from "./commands/setup.js";
 import { installGate, resolveGatePrefix } from "./commands/gate.js";
 import { claimAction, releaseAction } from "./commands/claim.js";
@@ -379,8 +379,14 @@ key
         }));
         console.log(`✓ Minted key: ${res.key}`);
         console.log("  (Shown once — store it now.)");
+        // RTSC-864: every paste form, now, while the key is still on the screen. A hosted
+        // agent or a container is the reason most people run this command at all, and
+        // until now it printed a bare key and left them to invent the config, which for
+        // Codex and Grok was not inventable, since no direct-form TOML block existed.
+        const cfg = loadConfig();
+        console.log("");
+        console.log(directFormBlocks(cfg.mcpUrl, res.key));
         if (opts.install) {
-            const cfg = loadConfig();
             console.log("");
             noteRuntimeIsALabel(opts.runtime);
             installMcp({ url: cfg.mcpUrl, key: res.key, scope: normalizeScope(opts.scope), watchdog: true });

package/dist/lib/harness.js

@@ -166,6 +166,36 @@ export function tomlBlock(entry) {
         env,
     ].join("\n");
 }
+/** The header table key each dialect actually reads. */
+const HTTP_HEADER_TABLE = {
+    codex: "http_headers",
+    grok: "headers",
+};
+/**
+ * The DIRECT-form `[mcp_servers.retasc]` block: talk to the remote MCP over HTTP with a
+ * bearer key, no local process (RTSC-864).
+ *
+ * The TOML counterpart of `mcpConfigBlock`, and the block that did not exist: `tomlBlock`
+ * above emits only the stdio proxy shape, so a Codex or Grok user on a host that cannot
+ * spawn a process (claude.ai connectors, Codex Cloud, a hosted OpenCode) had nothing
+ * correct to paste and no way to tell that from the JSON form.
+ *
+ * The key is written literally, exactly as the JSON block writes it, because the host
+ * this is pasted into is the one that has no environment for us to read. Both tools can
+ * take the key from the environment instead where there IS one (Codex:
+ * `bearer_token_env_var = "RETASC_MCP_KEY"`; Grok expands `${RETASC_MCP_KEY}` inside a
+ * header value), so prefer that, and never paste either form into a file the repo tracks.
+ */
+export function tomlHttpBlock(url, key, dialect) {
+    return [
+        `[mcp_servers.${SERVER_NAME}]`,
+        `url = ${JSON.stringify(url)}`,
+        `enabled = true`,
+        ``,
+        `[mcp_servers.${SERVER_NAME}.${HTTP_HEADER_TABLE[dialect]}]`,
+        `Authorization = ${JSON.stringify(`Bearer ${key}`)}`,
+    ].join("\n");
+}
 function tomlHarness(id, label, path, bin, skills) {
     return {
         id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.46.0",
+  "version": "1.47.0",
   "description": "Retasc CLI — 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": {