@agentvalet/mcp-server 1.2.0 → 1.4.0

package/dist/gate-client.js

@@ -0,0 +1,159 @@
+// apps/mcp-server/src/gate-client.ts
+//
+// A thin, dependency-free client over AgentValet's public governance contract.
+// It does NOT implement policy, brokering, or audit. Those live in the proxy.
+// It only does two things:
+//
+//   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
+//      a connector switches on a single discriminated union instead of
+//      re-deriving status-code semantics in every integration.
+//
+// The full wire contract these mappings depend on is documented in
+// docs/contract/public-governance-gate.md. Keep this file and that doc in step.
+//
+// fetch is injectable (fetchImpl) so the mapping is testable without a network;
+// it defaults to the global fetch.
+/** 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"]);
+function readField(body, key) {
+    if (body && typeof body === "object" && key in body) {
+        const v = body[key];
+        return typeof v === "string" ? v : undefined;
+    }
+    return undefined;
+}
+/**
+ * Pure mapper: a public-gate response (HTTP status + parsed body) to a decision.
+ * Exported so connectors and tests can classify a response they already hold.
+ *
+ * Mapping (POST /v1/actions):
+ *   2xx                                  -> allowed
+ *   202                                  -> pending_approval
+ *   403 reason in {agent_suspended,
+ *        circuit_breaker_open}           -> suspended
+ *   401 / 5xx                            -> error
+ *   other 4xx (402/403/412/429/...)      -> denied
+ */
+export function classifyGateResponse(status, body) {
+    if (status === 202) {
+        return {
+            decision: "pending_approval",
+            status,
+            approvalId: readField(body, "approval_id") ?? null,
+            message: readField(body, "message"),
+            raw: body,
+        };
+    }
+    if (status >= 200 && status < 300) {
+        return { decision: "allowed", status, data: body };
+    }
+    if (status === 403) {
+        const reason = readField(body, "reason");
+        if (reason && SUSPENDED_REASONS.has(reason)) {
+            return { decision: "suspended", status, reason, raw: body };
+        }
+    }
+    // Identity rejection and upstream/server failures are not policy decisions.
+    if (status === 401 || status >= 500) {
+        return {
+            decision: "error",
+            status,
+            code: readField(body, "code") ?? (status === 401 ? "unauthorized" : null),
+            correlationId: readField(body, "correlation_id"),
+            raw: body,
+        };
+    }
+    // Every other 4xx (402 billing, 403 policy, 412 not-connected, 429 rate) is a
+    // governance refusal of an otherwise-healthy agent.
+    return {
+        decision: "denied",
+        status,
+        reason: readField(body, "reason") ?? readField(body, "error") ?? null,
+        correlationId: readField(body, "correlation_id"),
+        raw: body,
+    };
+}
+async function parseBody(res) {
+    const text = await res.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * Call the public governance gate (POST /v1/actions) and return a classified
+ * outcome. Never throws for a gate response or a transport failure: a transport
+ * failure resolves to a GateError with code "network_error" so callers handle
+ * every path through the same switch.
+ */
+export async function callGate(client, req) {
+    const doFetch = client.fetchImpl ?? fetch;
+    const requestBody = {
+        platform: req.platform,
+        endpoint: req.endpoint,
+        method: req.method,
+        scope: req.scope,
+        ...(req.data !== undefined ? { data: req.data } : {}),
+        ...(req.connection_id ? { connection_id: req.connection_id } : {}),
+    };
+    let res;
+    try {
+        res = await doFetch(`${client.proxyUrl}/v1/actions`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${client.token}`, "Content-Type": "application/json" },
+            body: JSON.stringify(requestBody),
+        });
+    }
+    catch (err) {
+        return {
+            decision: "error",
+            status: 0,
+            code: "network_error",
+            raw: { error: err instanceof Error ? err.message : String(err) },
+        };
+    }
+    return classifyGateResponse(res.status, await parseBody(res));
+}
+/**
+ * Call the Observe relay (POST /v1/observe/actions). The relay is audit-only and
+ * passes the upstream status through, so a completed relay always resolves to
+ * GateObserved regardless of the upstream status. The BYO credential rides as a
+ * header and never enters the request body. A transport failure resolves to a
+ * GateError with code "network_error".
+ */
+export async function observe(client, req) {
+    const doFetch = client.fetchImpl ?? fetch;
+    const relayBody = {
+        platform: req.platform,
+        endpoint: req.endpoint,
+        method: req.method,
+        ...(req.action !== undefined ? { action: req.action } : {}),
+        ...(req.body !== undefined ? { body: req.body } : {}),
+    };
+    let res;
+    try {
+        res = await doFetch(`${client.proxyUrl}/v1/observe/actions`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${client.token}`,
+                "Content-Type": "application/json",
+                "X-AV-Observe-Credential": req.credential,
+            },
+            body: JSON.stringify(relayBody),
+        });
+    }
+    catch (err) {
+        return {
+            decision: "error",
+            status: 0,
+            code: "network_error",
+            raw: { error: err instanceof Error ? err.message : String(err) },
+        };
+    }
+    return { decision: "observed", status: res.status, data: await parseBody(res) };
+}

package/dist/index.js

@@ -22,7 +22,7 @@ import { validateConfig } from "./config.js";
 import { renderInstructions } from "./instructions.js";
 import { signJWT } from "./auth.js";
 import { ALLOWED_METHODS, ALL_TOOLS } from "./tools/schemas.js";
-import { handleListPlatforms, handleUsePlatform, handleAgentRegister, handleAgentStatus, handleAuthzenEvaluate, handleListMyPendingActions, handleReportSelfDiagnostic, } from "./tools/handlers.js";
+import { handleListPlatforms, handleUsePlatform, handleAgentRegister, handleAgentStatus, handleAuthzenEvaluate, handleListMyPendingActions, handleReportSelfDiagnostic, handleRequestPlatformAccess, } from "./tools/handlers.js";
 import { errorContent } from "./net.js";
 // ---------------------------------------------------------------------------
 // Startup env validation
@@ -43,7 +43,16 @@ process.stderr.write(`[mcp-server] config ok | agent=${AGENT_ID} | owner=${OWNER
 const server = new Server({ name: "agentvalet", version: "1.0.0" }, { capabilities: { tools: {} }, instructions: renderInstructions(undefined) });
 // The config + server bundle threaded into auth + handlers (see context.ts) —
 // keeps those modules free of globals.
-const ctx = { AGENT_ID, OWNER_ID, PROXY_URL, AGENT_PRIVATE_KEY_RAW, privateKey, server };
+const ctx = {
+    AGENT_ID,
+    OWNER_ID,
+    PROXY_URL,
+    AGENT_PRIVATE_KEY_RAW,
+    privateKey,
+    server,
+    OBSERVE_PLATFORM: process.env.OBSERVE_PLATFORM ?? "",
+    OBSERVE_CREDENTIAL: process.env.OBSERVE_CREDENTIAL ?? "",
+};
 // Boot-time platform fetch — primes the proxy connection and surfaces auth
 // failures in the stderr boot diagnostics. Best-effort and fire-and-forget so
 // it can NEVER delay the `initialize` response (a top-level await here used to
@@ -134,6 +143,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         return await handleReportSelfDiagnostic(ctx, args);
     }
+    if (name === "request_platform_access") {
+        if (!args || typeof args.platform !== "string") {
+            return errorContent("Invalid or missing argument: platform is required");
+        }
+        return await handleRequestPlatformAccess(ctx, args);
+    }
     return {
         content: [{ type: "text", text: `Unknown tool: ${name}` }],
         isError: true,

package/dist/tools/handlers.js

@@ -46,6 +46,44 @@ export async function handleUsePlatform(ctx, params, progressToken) {
     const gate = await requireCredentials(ctx);
     if (gate)
         return gate;
+    // Observe Mode: when a BYO credential is configured locally, route to the
+    // audit-only relay and attach the credential as a header (NEVER in the body —
+    // it must not enter model-visible tool args). Governed behaviour is unchanged
+    // when no observe credential is set.
+    //
+    // Platform-match guard: if OBSERVE_PLATFORM is set, only route to the observe
+    // relay when the requested platform matches — preventing BYO credential leakage
+    // to unrelated platforms. If OBSERVE_PLATFORM is empty, route observe for any
+    // platform (backwards-compat when only OBSERVE_CREDENTIAL is set).
+    const observePlatformMatch = ctx.OBSERVE_CREDENTIAL &&
+        (ctx.OBSERVE_PLATFORM === "" || ctx.OBSERVE_PLATFORM === params.platform);
+    if (observePlatformMatch) {
+        const observeBody = {
+            platform: params.platform,
+            endpoint: params.endpoint,
+            method: params.method,
+            action: params.scope,
+            ...(params.data !== undefined && { body: params.data }),
+        };
+        let response;
+        try {
+            // fetchWithAuth signs and attaches the AV agent JWT (Authorization: Bearer …).
+            // Content-Type: application/json is added by fetchWithAuth before spreading
+            // init.headers, so X-AV-Observe-Credential survives.
+            response = await fetchWithAuth(ctx, `${ctx.PROXY_URL}/v1/observe/actions`, {
+                method: "POST",
+                headers: { "X-AV-Observe-Credential": ctx.OBSERVE_CREDENTIAL },
+                body: JSON.stringify(observeBody),
+            });
+        }
+        catch (err) {
+            return errorContent(`Network error: ${err instanceof Error ? err.message : err}`);
+        }
+        const text = await response.text();
+        if (!response.ok)
+            return errorContent(`Proxy error ${response.status}: ${text}`);
+        return jsonContent(text);
+    }
     const requestBody = {
         platform: params.platform,
         endpoint: params.endpoint,
@@ -76,8 +114,15 @@ export async function handleUsePlatform(ctx, params, progressToken) {
             return await waitForApproval(ctx, approvalId, params, progressToken);
         }
     }
-    if (!response.ok)
-        return errorContent(`Proxy error ${response.status}: ${body}`);
+    if (!response.ok) {
+        // 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.
+        const hint = response.status === 403
+            ? "  You can call request_platform_access({ platform, scope, reason }) to ask an org admin to grant this."
+            : "";
+        return errorContent(`Proxy error ${response.status}: ${body}${hint}`);
+    }
     return jsonContent(body);
 }
 async function waitForApproval(ctx, approvalId, originalCall, progressToken) {
@@ -242,6 +287,59 @@ export async function handleListMyPendingActions(ctx) {
         return errorContent(`Proxy error ${response.status}: ${text}`);
     return jsonContent(text);
 }
+export async function handleRequestPlatformAccess(ctx, args) {
+    const gate = await requireCredentials(ctx);
+    if (gate)
+        return gate;
+    const platform = typeof args.platform === "string" ? args.platform : "";
+    if (!platform)
+        return errorContent("platform is required");
+    const scope = typeof args.scope === "string" ? args.scope : undefined;
+    const reason = typeof args.reason === "string" ? args.reason : undefined;
+    let submit;
+    try {
+        submit = await fetchWithAuth(ctx, `${ctx.PROXY_URL}/v1/access-request`, {
+            method: "POST",
+            body: JSON.stringify({ platform, scope, reason }),
+        });
+    }
+    catch (err) {
+        return errorContent(diagnoseNetworkError(err, ctx.PROXY_URL));
+    }
+    if (!submit.ok && submit.status !== 202 && submit.status !== 200) {
+        const t = await submit.text();
+        return errorContent(`Access request failed (${submit.status}): ${t}`);
+    }
+    const submitted = (await submit.json());
+    const token = submitted.request_token;
+    if (!token)
+        return errorContent("Access request did not return a token.");
+    // Poll the request status for ~50s (2s interval), matching use_platform UX.
+    const deadline = Date.now() + 50_000;
+    while (Date.now() < deadline) {
+        await sleep(2000);
+        let statusRes;
+        try {
+            statusRes = await fetchWithAuth(ctx, `${ctx.PROXY_URL}/v1/access-request/status/${encodeURIComponent(token)}`, { method: "GET" });
+        }
+        catch {
+            continue;
+        }
+        if (!statusRes.ok)
+            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." }));
+        }
+        if (s.status === "denied") {
+            return jsonContent(JSON.stringify({ status: "denied", message: "An admin denied this access request." }));
+        }
+    }
+    return jsonContent(JSON.stringify({
+        status: "pending",
+        message: "Request submitted and awaiting admin approval. Retry your call later.",
+    }));
+}
 export async function handleReportSelfDiagnostic(ctx, args) {
     const gate = await requireCredentials(ctx);
     if (gate)

package/dist/tools/schemas.js

@@ -261,6 +261,27 @@ export const LIST_MY_PENDING_ACTIONS_TOOL = {
         required: ["pending", "recently_completed"],
     },
 };
+export const REQUEST_PLATFORM_ACCESS_TOOL = {
+    name: "request_platform_access",
+    description: "request_platform_access: Ask an org admin to grant this agent access to a platform it is currently blocked from. Call this when use_platform returns an access-denied error. Input: platform (string, required), scope (string, optional — the specific scope you need), reason (string, optional — why you need it). The call waits up to ~50s for an admin decision. Returns: { status: \"approved\"|\"pending\"|\"denied\", message }. On \"approved\", retry your original use_platform call. On \"pending\", the request is queued; retry later. Auth: Bearer agent JWT (sent automatically).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            platform: { type: "string", description: "Platform ID (e.g. github, slack)" },
+            scope: { type: "string", description: "Optional specific scope needed (e.g. repo:read)" },
+            reason: { type: "string", description: "Optional short reason for the request" },
+        },
+        required: ["platform"],
+    },
+    outputSchema: {
+        type: "object",
+        properties: {
+            status: { type: "string", enum: ["approved", "pending", "denied"] },
+            message: { type: "string" },
+        },
+        required: ["status"],
+    },
+};
 export const ALL_TOOLS = [
     LIST_PLATFORMS_TOOL,
     USE_PLATFORM_TOOL,
@@ -269,4 +290,5 @@ export const ALL_TOOLS = [
     AUTHZEN_EVALUATE_TOOL,
     REPORT_SELF_DIAGNOSTIC_TOOL,
     LIST_MY_PENDING_ACTIONS_TOOL,
+    REQUEST_PLATFORM_ACCESS_TOOL,
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentvalet/mcp-server",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "AgentValet MCP server — lets AI agents call approved platforms via the AgentValet proxy",
   "type": "module",
   "main": "dist/index.js",