feat: add secure in-chat credential request cards

server/credential-request.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  CREDENTIAL_TARGETS,
+  credentialConfigPatch,
+  credentialIsConfigured,
+  credentialResumeOutcome,
+  isReusableCredentialRequest,
+  isCredentialTargetId,
+  type CredentialConfig,
+  type CredentialTargetId,
+} from "../shared/credential-request.ts";
+
+const MAPPINGS: Array<[CredentialTargetId, CredentialConfig]> = [
+  ["xaiApiKey", { xai: { key: "secret" } }],
+  ["boxToken", { box: { token: "secret" } }],
+  ["opencodeGoApiKey", { opencodeGo: { apiKey: "secret" } }],
+  ["ttsKey", { tts: { key: "secret" } }],
+  ["openaiImageApiKey", { imageGen: { key: "secret" } }],
+];
+
+describe("credential request allowlist", () => {
+  it("accepts only declared own ids", () => {
+    expect(isCredentialTargetId("xaiApiKey")).toBe(true);
+    expect(isCredentialTargetId("composioApiKey")).toBe(false);
+    expect(isCredentialTargetId("__proto__")).toBe(false);
+    expect(isCredentialTargetId({ toString: () => "xaiApiKey" })).toBe(false);
+  });
+
+  it("maps each id to a fixed config location", () => {
+    expect(MAPPINGS.map(([id]) => id).sort()).toEqual(Object.keys(CREDENTIAL_TARGETS).sort());
+    for (const [id, patch] of MAPPINGS) {
+      expect(credentialConfigPatch(id, "secret")).toEqual(patch);
+      expect(credentialIsConfigured(patch, id)).toBe(true);
+      expect(credentialIsConfigured({}, id)).toBe(false);
+    }
+  });
+
+  it("checks configured state without exposing values", () => {
+    expect(credentialIsConfigured({ tts: { key: "secret" } }, "ttsKey")).toBe(true);
+    expect(credentialIsConfigured({ tts: { key: "" } }, "ttsKey")).toBe(false);
+    expect(Object.keys(CREDENTIAL_TARGETS)).toHaveLength(5);
+  });
+
+  it("reuses open room cards only for the bot that requested them", () => {
+    const card = {
+      kind: "secret",
+      secret: { target: "xaiApiKey" },
+      from: { botId: "atlas" },
+    };
+    expect(isReusableCredentialRequest(card, "xaiApiKey", "atlas", true)).toBe(true);
+    expect(isReusableCredentialRequest(card, "xaiApiKey", "pixel", true)).toBe(false);
+    expect(isReusableCredentialRequest(card, "xaiApiKey", "pixel", false)).toBe(true);
+    expect(isReusableCredentialRequest({ ...card, secret: { ...card.secret, provided: true } }, "xaiApiKey", "atlas", true)).toBe(false);
+  });
+
+  it("preserves the original save or decline outcome when retrying", () => {
+    expect(credentialResumeOutcome({ provided: true })).toBe("provided");
+    expect(credentialResumeOutcome({ dismissed: true })).toBe("dismissed");
+    expect(credentialResumeOutcome({})).toBeNull();
+    expect(credentialResumeOutcome({ provided: true, dismissed: true })).toBeNull();
+  });
+});

server/drivers/agents-proxy.test.ts

@@ -21,6 +21,7 @@ let askResponse: unknown = { botName: "Helper", text: "hi from helper" };
 let lastDelegateBody: any = null;
 let delegateResponse: unknown = { queued: true, message: "Delegation queued." };
 let lastCreateBody: any = null;
+let lastCredentialBody: any = null;
 
 let child: ChildProcess;
 const pending = new Map<number, (msg: any) => void>();
@@ -83,6 +84,16 @@ beforeAll(async () => {
       });
       return;
     }
+    if (req.method === "POST" && req.url === "/api/internal/request-credential") {
+      let data = "";
+      req.on("data", (c) => (data += c));
+      req.on("end", () => {
+        lastCredentialBody = JSON.parse(data);
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ messageId: "msg-key", label: "OpenCode API key" }));
+      });
+      return;
+    }
     res.writeHead(404, { "content-type": "application/json" });
     res.end(JSON.stringify({ error: "unknown" }));
   });
@@ -121,7 +132,7 @@ afterAll(async () => {
 });
 
 describe("agents-proxy MCP surface", () => {
-  it("answers the MCP handshake and lists all four tools", async () => {
+  it("answers the MCP handshake and lists all five tools", async () => {
     const init = await rpc("initialize", { protocolVersion: "2024-11-05" });
     expect(init.result.serverInfo.name).toContain("agents");
     const list = await rpc("tools/list");
@@ -130,6 +141,7 @@ describe("agents-proxy MCP surface", () => {
       "ask_bot",
       "delegate_bot",
       "create_bot",
+      "request_credential",
     ]);
   });
 
@@ -210,6 +222,29 @@ describe("agents-proxy MCP surface", () => {
     });
   });
 
+  it("requests an allowlisted credential without putting a secret in the request", async () => {
+    const res = await callTool("request_credential", {
+      credential_id: "opencodeGoApiKey",
+      reason: "The selected model needs it.",
+    });
+    expect(res.result.content[0].text).toContain("secure OpenCode API key card");
+    expect(res.result.content[0].text).toContain("End this turn");
+    expect(lastCredentialBody).toEqual({
+      fromBotId: "bot-asker",
+      fromThreadId: "thread-asker-routine",
+      credentialId: "opencodeGoApiKey",
+      reason: "The selected model needs it.",
+    });
+    expect(JSON.stringify(lastCredentialBody)).not.toContain("secret");
+  });
+
+  it("rejects credential ids outside the fixed allowlist locally", async () => {
+    lastCredentialBody = null;
+    const res = await callTool("request_credential", { credential_id: "arbitrary.config.path" });
+    expect(res.result.isError).toBe(true);
+    expect(lastCredentialBody).toBeNull();
+  });
+
   it("rejects unknown tools with -32602", async () => {
     const res = await rpc("tools/call", { name: "made_up", arguments: {} });
     expect(res.error.code).toBe(-32602);

server/drivers/agents-proxy.ts

@@ -1,5 +1,5 @@
 // Agent-to-agent comms MCP proxy — spawned as an MCP server inside a bot's
-// agent process (via the "agents" integration). Exposes four tools that
+// agent process (via the "agents" integration). Exposes five tools that
 // let one bot talk to another, routed back through the harness so the
 // harness stays the single owner of turns, permissions, and recursion
 // limits:
@@ -12,6 +12,7 @@
 //                                          the peer's reply as its own turn
 //   create_bot(name, role, instructions) → Chiefs can add a specialist to
 //                                          their own section
+//   request_credential(id, reason?)       → show a secure, allowlisted key card
 //
 // Speaks raw JSON-RPC 2.0 over stdio (no MCP SDK — house style, matches
 // computer-proxy / permission-proxy). All state comes from env, injected by
@@ -22,6 +23,8 @@
 //   OMB_TURN_DEPTH   this turn's comms depth (the harness refuses recursion)
 import readline from "node:readline";
 
+import { CREDENTIAL_TARGETS, isCredentialTargetId } from "../../shared/credential-request.ts";
+
 const HARNESS = process.env.OMB_HARNESS_URL ?? "http://127.0.0.1:8799";
 const BOT_ID = process.env.OMB_BOT_ID ?? "";
 const THREAD_ID = process.env.OMB_THREAD_ID ?? "";
@@ -78,6 +81,26 @@ const TOOLS = [
       required: ["name", "role", "instructions"],
     },
   },
+  {
+    name: "request_credential",
+    description:
+      "Ask the user for a supported API key through OpenMausBot's secure credential card. Use this instead of asking them to paste a secret into chat. The secret is saved by the desktop app and is never returned to you. After calling this tool, end the turn; OpenMausBot resumes the task after the user saves or declines.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        credential_id: {
+          type: "string",
+          enum: Object.keys(CREDENTIAL_TARGETS),
+          description: "The credential the current task requires.",
+        },
+        reason: {
+          type: "string",
+          description: "Optional short, non-sensitive explanation of why the task needs it.",
+        },
+      },
+      required: ["credential_id"],
+    },
+  },
 ];
 
 type Json = Record<string, unknown>;
@@ -165,6 +188,28 @@ async function callTool(name: string, args: Json): Promise<{ text: string; isErr
       text: `Created @${r.name ?? botName} in ${r.section ?? "General"} [id: ${r.id}]. Assign work with delegate_bot.`,
     };
   }
+  if (name === "request_credential") {
+    const credentialId = args.credential_id;
+    if (!isCredentialTargetId(credentialId)) {
+      return { text: "request_credential needs a supported credential_id.", isError: true };
+    }
+    const reason = typeof args.reason === "string" ? args.reason.trim().slice(0, 240) : "";
+    const r = await api("/api/internal/request-credential", {
+      method: "POST",
+      body: JSON.stringify({
+        fromBotId: BOT_ID,
+        fromThreadId: THREAD_ID,
+        credentialId,
+        ...(reason ? { reason } : {}),
+      }),
+    });
+    if (r.alreadyConfigured) {
+      return { text: `${r.label ?? CREDENTIAL_TARGETS[credentialId].label} is already configured. Continue the task.` };
+    }
+    return {
+      text: `A secure ${r.label ?? CREDENTIAL_TARGETS[credentialId].label} card is now visible to the user. End this turn; OpenMausBot will resume the task after they save or decline. Never ask them to paste the key into chat.`,
+    };
+  }
   return { text: `Unknown tool: ${name}`, isError: true };
 }