@agentvalet/mcp-server 0.2.4 → 0.3.0

package/dist/index.js

@@ -49,12 +49,12 @@ function pendingFirstCallResponse() {
 const ALLOWED_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 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 array with platformId, platformName, scopes, requireApproval.\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 }], version: \"<hex>\" }.\nVersion: a deterministic hash that only changes when the platform set or scopes change. Cache the value across calls in the same session — only refresh when you suspect platforms have changed (e.g. user mentions a new connection).\nAuth: Bearer JWT.",
     inputSchema: { type: "object", properties: {} },
 };
 const USE_PLATFORM_TOOL = {
     name: "use_platform",
-    description: "use_platform: Call an external platform API (Airtable, GitHub, Slack, etc.) through the AgentValet proxy.\nInput: platform (string), endpoint (string), method (GET|POST|PUT|PATCH|DELETE), scope (string), data (object, optional).\nReturns: upstream API response body.\nAuth: Bearer JWT.",
+    description: "use_platform: Call an external platform API (Airtable, GitHub, Slack, etc.) through the AgentValet proxy.\nInput: platform (string), endpoint (string), method (GET|POST|PUT|PATCH|DELETE), scope (string), data (object, optional).\nReturns: upstream API response body. May take up to 50 seconds when the action requires owner approval — the call will block while we wait, then return the approved result transparently. If approval doesn't land in time, returns a `pending_approval` envelope and the action runs asynchronously; the user is notified when it completes.\nAuth: Bearer JWT.",
     inputSchema: {
         type: "object",
         properties: {
@@ -221,13 +221,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 isError: true,
             };
         }
+        const progressToken = request.params._meta?.progressToken;
         return await handleUsePlatform({
             platform: args.platform,
             endpoint: args.endpoint,
             method: args.method,
             scope: args.scope,
             data: args.data,
-        });
+        }, progressToken);
     }
     if (name === "agent_register") {
         if (!args || typeof args.owner_id !== "string" || typeof args.agent_name !== "string" || !Array.isArray(args.requested_scopes)) {
@@ -304,7 +305,13 @@ async function handleListPlatforms() {
         return errorContent(`Proxy error ${response.status}: ${body}`);
     return { content: [{ type: "text", text: body }] };
 }
-async function handleUsePlatform(params) {
+// Long-poll budget — under Claude Desktop's hardcoded 60s tool timeout
+// (with 10s of safety). After this we return a graceful "queued" message and
+// the action lands in the user's pending-actions list (Layer 4).
+const APPROVAL_POLL_BUDGET_MS = 50_000;
+const APPROVAL_POLL_INTERVAL_MS = 2_000;
+const APPROVAL_PROGRESS_INTERVAL_MS = 5_000;
+async function handleUsePlatform(params, progressToken) {
     if (AGENT_PRIVATE_KEY_RAW === null) {
         await notifyBindSecret();
         return pendingFirstCallResponse();
@@ -327,10 +334,112 @@ async function handleUsePlatform(params) {
         return errorContent(`Network error: ${err instanceof Error ? err.message : err}`);
     }
     const body = await response.text();
+    // 202 + approval_id → enter long-poll. The proxy returns this when the
+    // owner needs to approve the call. We poll /v1/approvals/:id every ~2s
+    // for up to 50s; if the owner approves in time the proxy re-runs the
+    // upstream call and we return its result to the agent transparently.
+    if (response.status === 202) {
+        const parsed = safeJsonParse(body);
+        const approvalId = parsed?.approval_id;
+        if (approvalId) {
+            return await waitForApproval(approvalId, params, progressToken);
+        }
+    }
     if (!response.ok)
         return errorContent(`Proxy error ${response.status}: ${body}`);
     return { content: [{ type: "text", text: body }] };
 }
+async function waitForApproval(approvalId, originalCall, progressToken) {
+    const startedAt = Date.now();
+    let lastProgressAt = 0;
+    // Initial progress so the user sees activity immediately.
+    await sendProgress(progressToken, 0, APPROVAL_POLL_BUDGET_MS, `Owner approval required for ${originalCall.platform}:${originalCall.scope} — waiting…`);
+    while (Date.now() - startedAt < APPROVAL_POLL_BUDGET_MS) {
+        await sleep(APPROVAL_POLL_INTERVAL_MS);
+        const elapsed = Date.now() - startedAt;
+        let res;
+        try {
+            res = await fetchWithAuth(`${PROXY_URL}/v1/approvals/${approvalId}`, { method: "GET" });
+        }
+        catch {
+            // Transient network error — try again next tick.
+            continue;
+        }
+        if (!res.ok) {
+            // 404/410 etc. — treat as terminal. Surface back to the agent.
+            const text = await res.text();
+            return errorContent(`Approval status error ${res.status}: ${text}`);
+        }
+        const status = (await res.json());
+        if (status.status === "approved" && status.executed_at && status.result) {
+            // Re-execution complete. Return the upstream response transparently —
+            // the agent sees this as if the original use_platform call just succeeded.
+            const r = status.result;
+            const summary = `[Owner approved after ${Math.round(elapsed / 1000)}s]\n` +
+                JSON.stringify(r.data ?? null);
+            // Mirror the non-2xx-from-upstream behaviour of the regular path.
+            if (r.status < 200 || r.status >= 300) {
+                return errorContent(`Upstream returned ${r.status}: ${JSON.stringify(r.data)}`);
+            }
+            return { content: [{ type: "text", text: summary }] };
+        }
+        if (status.status === "denied") {
+            return errorContent(`Owner denied this action${status.execution_error ? `: ${status.execution_error}` : "."}`);
+        }
+        if (status.status === "expired") {
+            return errorContent("Approval request expired before the owner responded.");
+        }
+        if (status.execution_error) {
+            // Approved but re-execution failed (network / upstream / agent revoked).
+            return errorContent(`Approved but re-execution failed: ${status.execution_error}`);
+        }
+        // Still pending — emit a progress update at most once per ~5s so the
+        // user can see the wait advancing in the Claude Desktop tool UI.
+        if (Date.now() - lastProgressAt >= APPROVAL_PROGRESS_INTERVAL_MS) {
+            await sendProgress(progressToken, elapsed, APPROVAL_POLL_BUDGET_MS, `Waiting for owner approval — ${Math.round(elapsed / 1000)}s elapsed`);
+            lastProgressAt = Date.now();
+        }
+    }
+    // Timed out — fall through to async-recap path. The action is still
+    // queued and will run when the owner approves; the user is notified via
+    // push/email at that point. Layer 4's list_my_pending_actions surfaces it.
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    status: "pending_approval",
+                    approval_id: approvalId,
+                    message: `Owner hasn't approved within ${APPROVAL_POLL_BUDGET_MS / 1000}s. ` +
+                        `The action is queued — your owner will be notified, and you'll see it ` +
+                        `complete next time we chat (or you can ask me to check pending actions).`,
+                }),
+            }],
+    };
+}
+function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function sendProgress(token, progress, total, message) {
+    if (token === undefined)
+        return;
+    try {
+        await server.notification({
+            method: "notifications/progress",
+            params: { progressToken: token, progress, total, message },
+        });
+    }
+    catch {
+        // Best-effort — never let a failed notification break the call.
+    }
+}
 async function handleAgentRegister(args) {
     let response;
     try {

package/dist/instructions.js

@@ -11,7 +11,8 @@ Tool selection:
 3. Call \`use_platform\` with the exact platform, endpoint, method, and scope returned by \`list_platforms\`.
 
 Response handling:
-- If \`use_platform\` returns \`pending_approval\`, wait — do not retry. The owner will approve out of band.
+- \`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.
 - 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/package.json

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