@agentvalet/mcp-server 1.15.0 → 1.18.0

package/dist/gate-client.js

@@ -6,7 +6,7 @@
 //
 //   1. Send a request to the public gate (POST /v1/actions) or the Observe
 //      relay (POST /v1/observe/actions).
-//   2. Map the wire response to exactly one of the six documented decisions, so
+//   2. Map the wire response to exactly one of the seven documented decisions, so
 //      a connector switches on a single discriminated union instead of
 //      re-deriving status-code semantics in every integration.
 //
@@ -18,6 +18,8 @@
 /** Agent states that mean "the agent itself is halted", surfaced as a 403 by the
  *  permission check. Distinct from a policy denial of an otherwise-healthy agent. */
 const SUSPENDED_REASONS = new Set(["agent_suspended", "circuit_breaker_open"]);
+/** An expired child identity (G6): permanent for this agent, so not "suspended". */
+const EXPIRED_REASONS = new Set(["agent_expired"]);
 function readField(body, key) {
     if (body && typeof body === "object" && key in body) {
         const v = body[key];
@@ -34,6 +36,7 @@ function readField(body, key) {
  *   202                                  -> pending_approval
  *   403 reason in {agent_suspended,
  *        circuit_breaker_open}           -> suspended
+ *   403 reason agent_expired             -> expired
  *   401 / 5xx                            -> error
  *   other 4xx (402/403/412/429/...)      -> denied
  */
@@ -55,6 +58,9 @@ export function classifyGateResponse(status, body) {
         if (reason && SUSPENDED_REASONS.has(reason)) {
             return { decision: "suspended", status, reason, raw: body };
         }
+        if (reason && EXPIRED_REASONS.has(reason)) {
+            return { decision: "expired", status, reason, raw: body };
+        }
     }
     // Identity rejection and upstream/server failures are not policy decisions.
     // 424 is the proxy's upstream-failure code (a 502/504 downgraded so

package/dist/index.js

@@ -180,6 +180,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             scope: args.scope,
             data: bodyArg,
             ...(typeof args.connection_id === "string" ? { connection_id: args.connection_id } : {}),
+            ...(args.caller && typeof args.caller === "object" ? { caller: args.caller } : {}),
             ...(typeof args.reason === "string" ? { reason: args.reason } : {}),
         }, progressToken);
     }
@@ -213,6 +214,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             // No `data` alias on the new tools: new surface, no legacy.
             ...(args.body !== undefined ? { data: args.body } : {}),
             ...(typeof args.connection_id === "string" ? { connection_id: args.connection_id } : {}),
+            ...(args.caller && typeof args.caller === "object" ? { caller: args.caller } : {}),
             ...(typeof args.reason === "string" ? { reason: args.reason } : {}),
         }, progressToken);
     }

package/dist/instructions.js

@@ -20,7 +20,7 @@ Matching a platform to a vendor: \`platformName\` is a label the OWNER typed and
 
 Response handling:
 - \`use_platform\` now waits up to 50 seconds for owner approval automatically. Most approvals complete in this window — the call simply takes longer and returns the upstream result like a normal success. Tell the user "waiting for owner approval" if the call is taking more than ~5 seconds.
-- If \`use_platform\` returns a \`pending_approval\` envelope after that wait, the action is queued and will run asynchronously when the owner approves. Tell the user clearly. Do NOT retry — duplicate calls will queue duplicate approvals.
+- If \`use_platform\` returns a \`pending_approval\` envelope after that wait, the action is queued and will run asynchronously when the owner approves. Tell the user clearly. Do NOT retry — wait, or check back later for the outcome. An identical retry while the approval is pending returns the same approval id (no second approval is queued), but it does not speed anything up.
 - Do not retry a denied call with a different scope.
 - If a \`use_platform\` error response includes a \`report_hint\` block, you may briefly ask the user "Want me to lodge this with your AgentValet owner?" — on yes, call \`report_self_diagnostic\` with a one-sentence narrative plus the \`correlation_id\` from the hint so the owner can investigate.
 

package/dist/registration-keys.js

@@ -0,0 +1,88 @@
+// apps/mcp-server/src/registration-keys.ts
+//
+// Local key custody for the agent_register -> owner approval -> agent_status
+// flow (Claude Desktop / MCPB self-registration).
+//
+// agent_register generates the RSA keypair HERE and sends only the public key
+// (POST /v1/register public_key_pem). The private key waits on disk, keyed by
+// the registration token, until agent_status sees the approval and installs it
+// as the agent's key. The private key never leaves this machine, never reaches
+// the dashboard, and is never put in a tool result the model can see.
+//
+// Layout (under ~/.agentvalet, dir 0700, key files 0600):
+//   pending/<registration_token>.key   private key awaiting approval
+//   agents/<agent_id>.key              installed key for an approved agent
+//   agent.key + agent.json             the DEFAULT identity config.ts boots
+//                                      from — written ONLY when neither file
+//                                      exists, so a registration never clobbers
+//                                      an identity another agent already owns
+//                                      (see invariant_register_clobbers_existing_agent_key).
+import { generateKeyPairSync } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentvaletDir, getIdentityPath, getKeyPath, persistBindArtifacts } from "./bind.js";
+const SAFE_SEGMENT = /^[A-Za-z0-9_-]{1,128}$/;
+export function generateRegistrationKeypair() {
+    return generateKeyPairSync("rsa", {
+        modulusLength: 2048,
+        publicKeyEncoding: { type: "spki", format: "pem" },
+        privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    });
+}
+function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+export function pendingKeyPath(token) {
+    if (!SAFE_SEGMENT.test(token))
+        return null;
+    return join(getAgentvaletDir(), "pending", `${token}.key`);
+}
+export function savePendingKey(token, privateKeyPem) {
+    const path = pendingKeyPath(token);
+    if (!path)
+        throw new Error("Unexpected registration token format; refusing to use it as a file name");
+    ensureDir(join(getAgentvaletDir(), "pending"));
+    writeFileSync(path, privateKeyPem, { mode: 0o600 });
+    return path;
+}
+export function readPendingKey(token) {
+    const path = pendingKeyPath(token);
+    if (!path || !existsSync(path))
+        return null;
+    try {
+        return readFileSync(path, "utf-8").trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function deletePendingKey(token) {
+    const path = pendingKeyPath(token);
+    if (path)
+        rmSync(path, { force: true });
+}
+/**
+ * Installs an approved agent's private key. Always writes
+ * agents/<agent_id>.key; additionally writes the default agent.key +
+ * agent.json when (and only when) no default identity exists yet, so the next
+ * server start picks it up with no env vars at all.
+ */
+export function installAgentKey(opts) {
+    if (!SAFE_SEGMENT.test(opts.agentId)) {
+        throw new Error("Unexpected agent_id format; refusing to use it as a file name");
+    }
+    const agentsDir = join(getAgentvaletDir(), "agents");
+    ensureDir(agentsDir);
+    const keyPath = join(agentsDir, `${opts.agentId}.key`);
+    writeFileSync(keyPath, opts.privateKeyPem, { mode: 0o600 });
+    const defaultTaken = existsSync(getKeyPath()) || existsSync(getIdentityPath());
+    if (!defaultTaken) {
+        persistBindArtifacts({
+            agent_id: opts.agentId,
+            owner_id: opts.ownerId,
+            proxy_url: opts.proxyUrl,
+            bound_at: new Date().toISOString(),
+        }, opts.privateKeyPem);
+    }
+    return { keyPath, becameDefault: !defaultTaken };
+}

package/dist/tools/handlers.js

@@ -8,6 +8,8 @@ import { errorContent, jsonContent, tryParseJson, safeJsonParse, sleep, diagnose
 import { requireCredentials, fetchWithAuth } from "../auth.js";
 import { recordPermissionsVersion } from "../permissions-watcher.js";
 import { parseConsentRefusal, elicitConsent, consentFallbackText, connectUrlFor } from "./consent.js";
+import { importPKCS8 } from "jose";
+import { generateRegistrationKeypair, savePendingKey, readPendingKey, deletePendingKey, installAgentKey, } from "../registration-keys.js";
 export async function handleListPlatforms(ctx) {
     const gate = await requireCredentials(ctx);
     if (gate)
@@ -99,6 +101,7 @@ consentRetried = false) {
         scope: params.scope,
         ...(params.data !== undefined && { data: params.data }),
         ...(params.connection_id ? { connection_id: params.connection_id } : {}),
+        ...(params.caller ? { caller: params.caller } : {}),
         // Agent-supplied justification. Forwarded verbatim; the proxy normalizes
         // and caps it before it reaches the approver's screen.
         ...(params.reason ? { reason: params.reason } : {}),
@@ -249,13 +252,34 @@ async function sendProgress(ctx, token, progress, total, message) {
         // Best-effort — never let a failed notification break the call.
     }
 }
+// Unwraps the proxy's { data, _meta } envelope when present.
+function unwrapData(parsed) {
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const obj = parsed;
+    if (obj.data && typeof obj.data === "object")
+        return obj.data;
+    return obj;
+}
+function structured(result) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        structuredContent: result,
+    };
+}
+// agent_register: the keypair is generated HERE and only the public key is
+// sent, so the private key never leaves this machine (and never transits the
+// owner's dashboard). It waits on disk until agent_status sees the approval.
 export async function handleAgentRegister(ctx, args) {
+    const { publicKey, privateKey } = generateRegistrationKeypair();
     let response;
     try {
         response = await fetchWithTimeout(`${ctx.PROXY_URL}/v1/register`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(args),
+            // public_key_pem last so a model-supplied value can never override it —
+            // we would not hold the matching private key.
+            body: JSON.stringify({ ...args, public_key_pem: publicKey }),
         });
     }
     catch (err) {
@@ -264,7 +288,65 @@ export async function handleAgentRegister(ctx, args) {
     const body = await response.text();
     if (!response.ok)
         return errorContent(`Proxy error ${response.status}: ${body}`);
-    return jsonContent(body);
+    const data = unwrapData(tryParseJson(body));
+    const token = typeof data?.registration_token === "string" ? data.registration_token : null;
+    if (!data || !token)
+        return jsonContent(body);
+    // Only keep the private key if the proxy actually bound our public key. An
+    // older proxy ignores public_key_pem and issues its own keypair; agent_status
+    // then collects that one via claim-key instead.
+    let keyStoredLocally = false;
+    if (data.keypair_source === "client") {
+        try {
+            savePendingKey(token, privateKey);
+            keyStoredLocally = true;
+        }
+        catch (err) {
+            return errorContent(`Registration ${token} was submitted, but the private key could not be saved locally ` +
+                `(${err instanceof Error ? err.message : err}). Ask the owner to reject it and register again.`);
+        }
+    }
+    return structured({
+        ...data,
+        key_stored_locally: keyStoredLocally,
+        next_step: "Ask the owner to approve this agent in the AgentValet dashboard, then call agent_status with the registration_token. " +
+            "The private key stays on this machine; agent_status installs it once approved.",
+    });
+}
+async function claimServerIssuedKey(ctx, token) {
+    try {
+        const res = await fetchWithTimeout(`${ctx.PROXY_URL}/v1/register/claim-key/${encodeURIComponent(token)}`, {
+            method: "GET",
+            headers: { "Content-Type": "application/json" },
+        });
+        if (!res.ok)
+            return null;
+        const json = (await res.json());
+        return typeof json.private_key === "string" && json.private_key.includes("PRIVATE KEY")
+            ? json.private_key
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+// If this server booted with no usable key (state B/C), adopt the newly
+// approved identity in-process so platform tools work without a restart.
+async function activateInProcess(ctx, agentId, ownerId, pem) {
+    if (ctx.AGENT_PRIVATE_KEY_RAW !== null)
+        return false;
+    if (ctx.AGENT_ID && ctx.AGENT_ID !== agentId)
+        return false;
+    try {
+        ctx.privateKey = await importPKCS8(pem, "RS256");
+    }
+    catch {
+        return false;
+    }
+    ctx.AGENT_ID = agentId;
+    ctx.OWNER_ID = ownerId;
+    ctx.AGENT_PRIVATE_KEY_RAW = pem;
+    return true;
 }
 export async function handleAgentStatus(ctx, token) {
     let response;
@@ -280,7 +362,76 @@ export async function handleAgentStatus(ctx, token) {
     const body = await response.text();
     if (!response.ok)
         return errorContent(`Proxy error ${response.status}: ${body}`);
-    return jsonContent(body);
+    const data = unwrapData(tryParseJson(body));
+    if (!data || typeof data.status !== "string")
+        return jsonContent(body);
+    if (data.status === "rejected" || data.status === "expired") {
+        deletePendingKey(token);
+        return structured(data);
+    }
+    if (data.status !== "approved")
+        return structured(data);
+    const agentId = typeof data.agent_id === "string" ? data.agent_id : "";
+    const mcpEnv = (data.mcp_config
+        ?.mcpServers?.agentvalet?.env) ?? {};
+    const ownerId = typeof data.owner_id === "string" ? data.owner_id : (mcpEnv.OWNER_ID ?? "");
+    // Locate the private key: our own (client keypair) or, for a legacy
+    // server-issued keypair, the one-time claim-key pickup.
+    let pem = null;
+    let source = null;
+    if (data.keypair_source === "client") {
+        pem = readPendingKey(token);
+        source = "client";
+    }
+    else {
+        pem = await claimServerIssuedKey(ctx, token);
+        source = "server";
+    }
+    const result = {
+        status: "approved",
+        agent_id: agentId,
+        owner_id: ownerId,
+        keypair_source: source,
+    };
+    if (!pem || !agentId || !ownerId) {
+        result.key_installed = false;
+        result.next_step =
+            source === "client"
+                ? "Approved, but this machine does not hold the private key for this registration (it was generated by a different install, or already installed). " +
+                    "Check ~/.agentvalet/agents/, or register again from this machine."
+                : "Approved, but the one-time private key could not be collected (already claimed, or the 5-minute window after approval has passed). " +
+                    "Register again from this machine so the key is generated locally.";
+        return structured(result);
+    }
+    let installed;
+    try {
+        installed = installAgentKey({ agentId, ownerId, proxyUrl: ctx.PROXY_URL, privateKeyPem: pem });
+    }
+    catch (err) {
+        return errorContent(`Approved as ${agentId}, but the private key could not be saved: ${err instanceof Error ? err.message : err}`);
+    }
+    deletePendingKey(token);
+    const activated = await activateInProcess(ctx, agentId, ownerId, pem);
+    result.key_installed = true;
+    result.key_path = installed.keyPath;
+    result.default_identity = installed.becameDefault;
+    result.activated = activated;
+    // The config to use this agent elsewhere: a key PATH, never the key itself.
+    result.mcp_config = {
+        mcpServers: {
+            agentvalet: {
+                command: "npx",
+                args: ["-y", "@agentvalet/mcp-server"],
+                env: { AGENT_ID: agentId, OWNER_ID: ownerId, PROXY_URL: ctx.PROXY_URL, AGENT_PRIVATE_KEY_PATH: installed.keyPath },
+            },
+        },
+    };
+    result.next_step = activated
+        ? "Registered and active in this session. Call list_platforms to see what the owner granted."
+        : installed.becameDefault
+            ? "Registered. The key is installed as this machine's default AgentValet identity; restart the MCP server (or Claude Desktop) to use it."
+            : "Registered. Another AgentValet identity is already configured on this machine, so it was left untouched; use the mcp_config above (AGENT_PRIVATE_KEY_PATH) to run this agent.";
+    return structured(result);
 }
 export async function handleAuthzenEvaluate(ctx, platformId, scope) {
     const gate = await requireCredentials(ctx);

package/dist/tools/schemas.js

@@ -98,6 +98,11 @@ export const USE_PLATFORM_TOOL = {
                 type: "string",
                 description: "Optional. Target a specific connection when a platform has more than one connected (e.g. two GitHub orgs). Value is the connection id shown in the dashboard. Omit to use the default connection.",
             },
+            caller: {
+                type: "object",
+                description: "Optional. Who the human is that this call is for, when this agent serves many people: { assertion: '<JWT from an identity provider the org registered>' } (verified) or { source, id } (asserted; honoured only where the platform allows it). On a platform with per-person tokens, the person's own upstream token is used; if they have not authorized yet the call returns consent_required with a consent_url to give them.",
+                properties: { assertion: { type: "string" }, source: { type: "string" }, id: { type: "string" } },
+            },
             reason: {
                 type: "string",
                 description: "Optional but strongly encouraged. One sentence on WHY you are making this call. If the action requires owner approval, this is shown to the human who decides — without it their approval is a blind yes/no. Max 500 characters (longer is truncated). Plain text; markup is not rendered.",
@@ -125,6 +130,11 @@ export const READ_PLATFORM_TOOL = {
                 type: "string",
                 description: "Optional. Target a specific connection when a platform has more than one connected. Omit to use the default.",
             },
+            caller: {
+                type: "object",
+                description: "Optional. Who the human is that this call is for, when this agent serves many people: { assertion: '<JWT from an identity provider the org registered>' } (verified) or { source, id } (asserted; honoured only where the platform allows it). On a platform with per-person tokens, the person's own upstream token is used; if they have not authorized yet the call returns consent_required with a consent_url to give them.",
+                properties: { assertion: { type: "string" }, source: { type: "string" }, id: { type: "string" } },
+            },
             reason: {
                 type: "string",
                 description: "Optional but strongly encouraged. One sentence on WHY you are making this call. Shown to the human approver if the call is gated. Max 500 characters; plain text.",
@@ -140,7 +150,7 @@ export const WRITE_PLATFORM_TOOL = {
         type: "object",
         properties: {
             platform: { type: "string", description: "Platform ID (e.g. github, slack, stripe)" },
-            endpoint: { type: "string", description: "Path in the platform's own API (e.g. /api/chat.postMessage)" },
+            endpoint: { type: "string", description: "Path in the platform's own API (e.g. /chat.postMessage)" },
             method: {
                 type: "string",
                 enum: ["POST", "PUT", "PATCH"],
@@ -156,6 +166,11 @@ export const WRITE_PLATFORM_TOOL = {
                 type: "string",
                 description: "Optional. Target a specific connection when a platform has more than one connected. Omit to use the default.",
             },
+            caller: {
+                type: "object",
+                description: "Optional. Who the human is that this call is for, when this agent serves many people: { assertion: '<JWT from an identity provider the org registered>' } (verified) or { source, id } (asserted; honoured only where the platform allows it). On a platform with per-person tokens, the person's own upstream token is used; if they have not authorized yet the call returns consent_required with a consent_url to give them.",
+                properties: { assertion: { type: "string" }, source: { type: "string" }, id: { type: "string" } },
+            },
             reason: {
                 type: "string",
                 description: "Optional but strongly encouraged. One sentence on WHY you are making this call. Shown to the human approver if the call is gated. Max 500 characters; plain text.",
@@ -181,6 +196,11 @@ export const DELETE_PLATFORM_TOOL = {
                 type: "string",
                 description: "Optional. Target a specific connection when a platform has more than one connected. Omit to use the default.",
             },
+            caller: {
+                type: "object",
+                description: "Optional. Who the human is that this call is for, when this agent serves many people: { assertion: '<JWT from an identity provider the org registered>' } (verified) or { source, id } (asserted; honoured only where the platform allows it). On a platform with per-person tokens, the person's own upstream token is used; if they have not authorized yet the call returns consent_required with a consent_url to give them.",
+                properties: { assertion: { type: "string" }, source: { type: "string" }, id: { type: "string" } },
+            },
             reason: {
                 type: "string",
                 description: "Optional but strongly encouraged. One sentence on WHY you are deleting this. Shown to the human approver if the call is gated. Max 500 characters; plain text.",
@@ -191,7 +211,7 @@ export const DELETE_PLATFORM_TOOL = {
 };
 export const AGENT_REGISTER_TOOL = {
     name: "agent_register",
-    description: "agent_register: Self-register this agent with an owner. No auth required.\nInput: owner_id (string), agent_name (string), requested_scopes (array of {platformId, scopes}).\nReturns: registration_token, poll_url, client_id, scope, expires_in.\nAuth: None.",
+    description: "agent_register: Self-register this agent with an owner. No auth required.\nInput: owner_id (string), agent_name (string), requested_scopes (array of {platformId, scopes}).\nThe agent's RSA keypair is generated on this machine; only the public key is sent and the private key stays here.\nReturns: registration_token, poll_url, client_id, scope, keypair_source, key_stored_locally.\nNext: once the owner approves in the dashboard, call agent_status with the registration_token to install the key.\nAuth: None.",
     inputSchema: {
         type: "object",
         properties: {
@@ -226,13 +246,15 @@ export const AGENT_REGISTER_TOOL = {
             client_id: { type: "string" },
             scope: { type: "string" },
             expires_in: { type: "number" },
+            keypair_source: { type: "string", enum: ["client", "server"] },
+            key_stored_locally: { type: "boolean" },
         },
         required: ["registration_token"],
     },
 };
 export const AGENT_STATUS_TOOL = {
     name: "agent_status",
-    description: "agent_status: Poll registration status using the token from agent_register.\nInput: token (string, required).\nReturns: status (\"pending_approval\"|\"approved\"|\"rejected\"), agent_id (if approved), mcp_config (if approved).\nAuth: None.",
+    description: "agent_status: Poll registration status using the token from agent_register.\nInput: token (string, required).\nOn approval it installs the agent's private key on this machine (~/.agentvalet/agents/<agent_id>.key, plus the default identity if none exists) and activates it for this session when the server had no identity yet. The private key is never returned in the result.\nReturns: status (\"pending\"|\"approved\"|\"rejected\"|\"expired\"), agent_id, key_installed, key_path, activated, mcp_config (if approved).\nAuth: None.",
     inputSchema: {
         type: "object",
         properties: {
@@ -246,8 +268,11 @@ export const AGENT_STATUS_TOOL = {
     outputSchema: {
         type: "object",
         properties: {
-            status: { type: "string", enum: ["pending_approval", "approved", "rejected"] },
+            status: { type: "string", enum: ["pending", "pending_approval", "approved", "rejected", "expired"] },
             agent_id: { type: "string" },
+            key_installed: { type: "boolean" },
+            key_path: { type: "string" },
+            activated: { type: "boolean" },
             mcp_config: { type: "object" },
         },
         required: ["status"],
@@ -356,9 +381,10 @@ export const LIST_MY_PENDING_ACTIONS_TOOL = {
                         platform_id: { type: "string" },
                         scope: { type: "string" },
                         status: { type: "string" },
-                        executed_at: { type: "string" },
-                        result_summary: { type: "string" },
-                        execution_error: { type: "string" },
+                        // null until there is something to report (expired, denied, not yet run).
+                        executed_at: { type: ["string", "null"] },
+                        result_summary: { type: ["string", "null"] },
+                        execution_error: { type: ["string", "null"] },
                     },
                     required: ["approval_id", "status"],
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentvalet/mcp-server",
-  "version": "1.15.0",
+  "version": "1.18.0",
   "description": "AgentValet MCP server — lets AI agents call approved platforms via the AgentValet proxy",
   "mcpName": "io.github.agentvalet/mcp-server",
   "type": "module",