@agentvalet/mcp-server 1.14.0 → 1.17.0

package/dist/gate-client.js

@@ -57,7 +57,9 @@ export function classifyGateResponse(status, body) {
         }
     }
     // Identity rejection and upstream/server failures are not policy decisions.
-    if (status === 401 || status >= 500) {
+    // 424 is the proxy's upstream-failure code (a 502/504 downgraded so
+    // Cloudflare doesn't swap the diagnostic body for its own error page).
+    if (status === 401 || status === 424 || status >= 500) {
         return {
             decision: "error",
             status,

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/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/consent.js

@@ -0,0 +1,145 @@
+// apps/mcp-server/src/tools/consent.ts
+//
+// Elicit mode for MCP server consent (CodePrompts/Affindi-Competitor/
+// 01-elicit-consent-mcp-design.md, Wave B).
+//
+// The proxy answers 409 needs_consent when an agent is granted on a remote
+// MCP OAuth server nobody has authorised yet, and (since 01) the body carries
+// the access request that tracks the consent: request_token, poll_url. This
+// long-lived stdio server has what the stateless remote surface lacks, a
+// server→client channel, so it can HOLD the call: hand the human the consent
+// link through MCP elicitation, wait for the request to flip to approved, and
+// let the caller retry inline. No "ask the agent to try again".
+//
+// Mode is derived per client, never stored (design Q4):
+//   client advertises elicitation.url  → elicitInput({ mode: "url" })
+//   client advertises elicitation.form → a one-field form that says where to
+//                                        go and asks to be told when done
+//   neither                            → on-demand text with the link
+// The SDK throws when a mode is used the client did not advertise, so the
+// capability is read first and the fallback is chosen before any request.
+//
+// The link is built HERE from the dashboard origin plus the token, never
+// taken from the proxy body: the host opens it on the user's behalf and must
+// not be steerable by anything the response could carry (inv-123's rule,
+// applied to the second surface).
+import { fetchWithAuth } from "../auth.js";
+import { sleep } from "../net.js";
+export const DASHBOARD_URL = (process.env.AGENTVALET_DASHBOARD_URL ?? "https://app.agentvalet.ai").replace(/\/$/, "");
+/** How long a held call waits for the admin to finish the consent screen. */
+export const CONSENT_POLL_BUDGET_MS = Number(process.env.AGENTVALET_CONSENT_POLL_BUDGET_MS ?? 90_000);
+const CONSENT_POLL_INTERVAL_MS = 2_000;
+export function connectUrlFor(requestToken) {
+    return `${DASHBOARD_URL}/connect?token=${encodeURIComponent(requestToken)}`;
+}
+export function parseConsentRefusal(status, body) {
+    if (status !== 409)
+        return null;
+    try {
+        const j = JSON.parse(body);
+        if (j.error !== "needs_consent" || typeof j.request_token !== "string" || !j.request_token)
+            return null;
+        return {
+            request_token: j.request_token,
+            platform: typeof j.platform === "string" ? j.platform : "the MCP server",
+            ...(typeof j.message === "string" ? { message: j.message } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Which elicitation the connected client advertised at initialize. */
+export function elicitModeFor(ctx) {
+    try {
+        const caps = ctx.server
+            .getClientCapabilities?.();
+        const e = caps?.elicitation;
+        if (!e || typeof e !== "object")
+            return "none";
+        if (e.url && typeof e.url === "object")
+            return "url";
+        // The SDK normalises a bare `elicitation: {}` to `{ form: {} }`.
+        if (e.form && typeof e.form === "object")
+            return "form";
+        return "none";
+    }
+    catch {
+        return "none";
+    }
+}
+/**
+ * Hold the call through the consent. Returns "approved" once the request the
+ * proxy raised reports approved (the OAuth callback flips it), so the caller
+ * can retry inline; every other outcome means the caller should answer with
+ * the on-demand text and the link.
+ */
+export async function elicitConsent(ctx, refusal) {
+    const mode = elicitModeFor(ctx);
+    if (mode === "none")
+        return { kind: "unsupported" };
+    const url = connectUrlFor(refusal.request_token);
+    const message = `An admin needs to authorize AgentValet with ${refusal.platform} before this agent can use it. ` +
+        `Open the link, sign in to AgentValet and press Authorize; this call resumes on its own when that lands.`;
+    const server = ctx.server;
+    let action;
+    try {
+        if (mode === "url") {
+            const res = await server.elicitInput({ mode: "url", message, url, elicitationId: refusal.request_token }, { timeout: CONSENT_POLL_BUDGET_MS });
+            action = res.action;
+        }
+        else {
+            const res = await server.elicitInput({
+                mode: "form",
+                message: `${message}\n\n${url}`,
+                requestedSchema: {
+                    type: "object",
+                    properties: {
+                        authorized: { type: "boolean", title: "I have completed the authorization", default: false },
+                    },
+                    required: ["authorized"],
+                },
+            }, { timeout: CONSENT_POLL_BUDGET_MS });
+            action = res.action === "accept" && res.content?.authorized === true ? "accept" : "decline";
+        }
+    }
+    catch {
+        // A host that advertised the capability but failed the request is the
+        // same as one without it: fall back to the text path.
+        return { kind: "unsupported" };
+    }
+    if (action !== "accept")
+        return { kind: "declined" };
+    // URL mode returns "accept" when the user has been shown the link, not when
+    // the consent is finished; the access request is the truth, so poll it.
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < CONSENT_POLL_BUDGET_MS) {
+        let res;
+        try {
+            res = await fetchWithAuth(ctx, `${ctx.PROXY_URL}/v1/access-request/status/${encodeURIComponent(refusal.request_token)}`, { method: "GET" });
+        }
+        catch {
+            await sleep(CONSENT_POLL_INTERVAL_MS);
+            continue;
+        }
+        if (res.ok) {
+            const s = (await res.json());
+            if (s.status === "approved")
+                return { kind: "approved", waited_ms: Date.now() - startedAt };
+            if (s.status === "denied" || s.status === "expired")
+                return { kind: "denied" };
+        }
+        await sleep(CONSENT_POLL_INTERVAL_MS);
+    }
+    return { kind: "timeout" };
+}
+/** The on-demand text every fallback returns: the link, and what to do with it. */
+export function consentFallbackText(refusal, outcome) {
+    const url = connectUrlFor(refusal.request_token);
+    const why = outcome.kind === "declined" ? "The authorization was not completed in this session."
+        : outcome.kind === "timeout" ? `The admin has not finished authorizing within ${Math.round(CONSENT_POLL_BUDGET_MS / 1000)}s.`
+            : outcome.kind === "denied" ? "The consent request was denied or expired."
+                : `This agent has not been authorized on ${refusal.platform} yet.`;
+    return (`${why} An AgentValet admin can authorize it here: ${url} ` +
+        "Give the user that link; retry the call once they confirm it is done.");
+}

package/dist/tools/handlers.js

@@ -7,6 +7,9 @@
 import { errorContent, jsonContent, tryParseJson, safeJsonParse, sleep, diagnoseNetworkError, fetchWithTimeout, } from "../net.js";
 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)
@@ -46,7 +49,10 @@ export async function handleListPlatforms(ctx) {
 const APPROVAL_POLL_BUDGET_MS = 50_000;
 const APPROVAL_POLL_INTERVAL_MS = 2_000;
 const APPROVAL_PROGRESS_INTERVAL_MS = 5_000;
-export async function handleUsePlatform(ctx, params, progressToken) {
+export async function handleUsePlatform(ctx, params, progressToken, 
+// Set on the single inline retry after a completed consent, so a server
+// that keeps answering 409 cannot loop this handler.
+consentRetried = false) {
     const gate = await requireCredentials(ctx);
     if (gate)
         return gate;
@@ -95,6 +101,7 @@ export async function handleUsePlatform(ctx, params, progressToken) {
         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 } : {}),
@@ -122,6 +129,30 @@ export async function handleUsePlatform(ctx, params, progressToken) {
         }
     }
     if (!response.ok) {
+        // 409 needs_consent with a request token: the one refusal a human can
+        // finish from a link. Hold the call through MCP elicitation when the
+        // client supports it and retry once the consent lands (01, Wave B);
+        // otherwise answer with the link in-band (closes gap-053 for this code).
+        const consent = parseConsentRefusal(response.status, body);
+        if (consent) {
+            const outcome = consentRetried ? { kind: "unsupported" } : await elicitConsent(ctx, consent);
+            if (outcome.kind === "approved") {
+                return await handleUsePlatform(ctx, params, progressToken, true);
+            }
+            const summary = consentFallbackText(consent, outcome);
+            return {
+                content: [{ type: "text", text: `Proxy error 409: ${summary}` }],
+                structuredContent: {
+                    error: "needs_consent",
+                    reason_code: "needs_consent",
+                    platform: consent.platform,
+                    request_token: consent.request_token,
+                    connect_url: connectUrlFor(consent.request_token),
+                    consent_outcome: outcome.kind,
+                },
+                isError: true,
+            };
+        }
         // 403 is the access-denied / scope-not-granted code returned by the
         // proxy's authorize pipeline (see apps/proxy/src/pipeline/authorize.ts).
         // Point the agent at request_platform_access instead of dead-ending it.
@@ -221,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) {
@@ -236,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;
@@ -252,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);
@@ -321,6 +500,28 @@ export async function handleRequestPlatformAccess(ctx, args) {
     const token = submitted.request_token;
     if (!token)
         return errorContent("Access request did not return a token.");
+    // The human hand-off link, for every reason a human can fix on that page.
+    // Built here from the dashboard origin, never taken from the response.
+    // scope_denied is excluded: a policy block is not fixable there, and a link
+    // that cannot work is worse than none. (Closes gap-053 on this surface.)
+    const actionable = ["not_connected", "not_granted", "needs_consent"].includes(submitted.reason_code ?? "");
+    const connectUrl = actionable ? connectUrlFor(token) : undefined;
+    const withLink = (o) => (connectUrl ? { ...o, connect_url: connectUrl } : o);
+    // A consent request can be held open through elicitation the same way a
+    // use_platform call is: the admin gets the link now, and this tool returns
+    // approved the moment the OAuth callback flips the request.
+    if (submitted.reason_code === "needs_consent") {
+        const outcome = await elicitConsent(ctx, { request_token: token, platform });
+        if (outcome.kind === "approved") {
+            return jsonContent(JSON.stringify(withLink({ status: "approved", message: "Authorized — retry your original use_platform call." })));
+        }
+        if (outcome.kind === "denied") {
+            return jsonContent(JSON.stringify({ status: "denied", message: "An admin denied this access request." }));
+        }
+        if (outcome.kind !== "unsupported") {
+            return jsonContent(JSON.stringify(withLink({ status: "pending", reason_code: "needs_consent", message: consentFallbackText({ request_token: token, platform }, outcome) })));
+        }
+    }
     // Poll the request status for ~50s (2s interval), matching use_platform UX.
     const deadline = Date.now() + 50_000;
     while (Date.now() < deadline) {
@@ -336,16 +537,19 @@ export async function handleRequestPlatformAccess(ctx, args) {
             continue;
         const s = (await statusRes.json());
         if (s.status === "approved") {
-            return jsonContent(JSON.stringify({ status: "approved", message: "Access granted — retry your original use_platform call." }));
+            return jsonContent(JSON.stringify(withLink({ status: "approved", message: "Access granted — retry your original use_platform call." })));
         }
         if (s.status === "denied") {
             return jsonContent(JSON.stringify({ status: "denied", message: "An admin denied this access request." }));
         }
     }
-    return jsonContent(JSON.stringify({
+    return jsonContent(JSON.stringify(withLink({
         status: "pending",
-        message: "Request submitted and awaiting admin approval. Retry your call later.",
-    }));
+        reason_code: submitted.reason_code,
+        message: connectUrl
+            ? `Request submitted and awaiting admin approval. Give the user this link so an admin can finish it: ${connectUrl} Retry your call once they confirm.`
+            : "Request submitted and awaiting admin approval. Retry your call later.",
+    })));
 }
 export async function handleIssueChildAgent(ctx, args) {
     const gate = await requireCredentials(ctx);

package/dist/tools/schemas.js

@@ -7,7 +7,7 @@
 export const ALLOWED_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 export const LIST_PLATFORMS_TOOL = {
     name: "list_platforms",
-    description: "list_platforms: List the platforms and permission scopes this agent has access to.\nInput: None.\nReturns: { platforms: [{ platformId, platformName, scopes, requireApproval, approvalScopes?, connections?, callStyle? }], version: \"<hex>\" }. A platform includes `connections` when it has 2+ usable accounts, or when one account carries context worth knowing; pass the chosen connection_id to use_platform (omit for the default). Each connection may carry `identity` (the account it actually points at, e.g. {email}) and `hint` (free text the owner wrote for you). Use them to resolve an instruction that names an account rather than a connection — \"send it from the aifirstpartner account\" means the connection whose identity.email or hint matches; if none does, ask rather than guessing the default.\nCall style: `callStyle` is present only as \"graphql\", and says how to ADDRESS the platform rather than what you may do there: that platform has ONE endpoint taking {query, variables} via POST, so pass \"/\" as the endpoint and put the operation in the body. Its path and HTTP method carry no meaning, read_platform cannot be used on it at all, and a GET returns an upstream error naming neither the platform nor the cause. Absent means a conventional REST API.\nApproval: a call needs human approval if the platform's requireApproval is true (grant-level: every call prompts), if the chosen connection's requireApproval is true, or if the scope is listed in approvalScopes (policy-level: just those scopes prompt). approvalScopes is omitted when no scope is policy-gated.\nVersion: a deterministic hash over the effective spec — it changes whenever the platform set, the scopes, the approval requirements (grant or policy), or the connections change. Compare it against the `Current permissions version` stamped on this description: if they differ, your cached result is stale and you must call list_platforms again before trusting it.\nAuth: Bearer JWT.",
+    description: "list_platforms: List the platforms and permission scopes this agent has access to.\nInput: None.\nReturns: { platforms: [{ platformId, platformName, scopes, requireApproval, approvalScopes?, connections?, callStyle? }], version: \"<hex>\" }. A platform includes `connections` when it has 2+ usable accounts, or when one account carries context worth knowing; pass the chosen connection_id to use_platform (omit for the default). Each connection may carry `identity` (the account it actually points at, e.g. {email}) and `hint` (free text the owner wrote for you). Use them to resolve an instruction that names an account rather than a connection — \"send it from the aifirstpartner account\" means the connection whose identity.email or hint matches; if none does, ask rather than guessing the default.\nCall style: `callStyle` is present only as \"graphql\", and says how to ADDRESS the platform rather than what you may do there: that platform has ONE endpoint taking {query, variables} via POST, so pass \"/\" as the endpoint and put the operation in the body. Its path and HTTP method carry no meaning, read_platform cannot be used on it at all, and a GET returns an upstream error naming neither the platform nor the cause. Absent means a conventional REST API.\nApproval: a call needs human approval if the platform's requireApproval is true (grant-level: every call prompts), if the chosen connection's requireApproval is true, or if the scope is listed in approvalScopes (policy-level: just those scopes prompt). approvalScopes is omitted when no scope is policy-gated.\nVersion: a deterministic hash over the effective spec — it changes whenever the platform set, the scopes, the approval requirements (grant or policy), or the connections change. Compare it against the `Current permissions version` stamped on this description: if they differ, your cached result is stale and you must call list_platforms again before trusting it.\nA platform block may carry `constraints` (recipient allow-lists: domains, addresses, channels). When present, address only those recipients; a call to anyone else is refused with 403 recipient_not_allowed.\nAuth: Bearer JWT.",
     inputSchema: { type: "object", properties: {} },
     outputSchema: {
         type: "object",
@@ -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.",
@@ -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"],

package/package.json

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