@agentvalet/mcp-server 0.2.5 → 0.3.1

package/dist/index.js

@@ -54,7 +54,7 @@ const LIST_PLATFORMS_TOOL = {
 };
 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: {
@@ -184,6 +184,11 @@ const REPORT_SELF_DIAGNOSTIC_TOOL = {
         required: ["severity", "message"],
     },
 };
+const LIST_MY_PENDING_ACTIONS_TOOL = {
+    name: "list_my_pending_actions",
+    description: "list_my_pending_actions: Returns this agent's currently-pending approval requests AND any that completed in the last 24 hours. Use this at session start when the user mentions an earlier action, or when use_platform's long-poll timed out and the user comes back asking what happened.\nInput: None.\nReturns: { pending: [{approval_id, platform_id, scope, created_at, expires_at}], recently_completed: [{approval_id, platform_id, scope, status, executed_at, result_summary, execution_error}] }.\nAuth: Bearer agent JWT (sent automatically).",
+    inputSchema: { type: "object", properties: {} },
+};
 // TODO: intent_resolve tool — planned for future release
 // ---------------------------------------------------------------------------
 // MCP server setup
@@ -197,6 +202,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         AGENT_STATUS_TOOL,
         AUTHZEN_EVALUATE_TOOL,
         REPORT_SELF_DIAGNOSTIC_TOOL,
+        LIST_MY_PENDING_ACTIONS_TOOL,
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -221,13 +227,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)) {
@@ -247,6 +254,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         return await handleAuthzenEvaluate(args.platform_id, args.scope);
     }
+    if (name === "list_my_pending_actions") {
+        return await handleListMyPendingActions();
+    }
     if (name === "report_self_diagnostic") {
         if (!args || typeof args.severity !== "string" || typeof args.message !== "string") {
             return errorContent("Invalid or missing arguments: severity and message are required");
@@ -304,7 +314,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 +343,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 {
@@ -385,6 +503,23 @@ async function handleAuthzenEvaluate(platformId, scope) {
         return errorContent(`Proxy error ${response.status}: ${body}`);
     return { content: [{ type: "text", text: body }] };
 }
+async function handleListMyPendingActions() {
+    if (AGENT_PRIVATE_KEY_RAW === null) {
+        await notifyBindSecret();
+        return pendingFirstCallResponse();
+    }
+    let response;
+    try {
+        response = await fetchWithAuth(`${PROXY_URL}/v1/agents/me/pending-actions`, { method: "GET" });
+    }
+    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 { content: [{ type: "text", text }] };
+}
 async function handleReportSelfDiagnostic(args) {
     if (AGENT_PRIVATE_KEY_RAW === null) {
         await notifyBindSecret();

package/dist/instructions.js

@@ -11,8 +11,12 @@ 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.
 
-Read scopes are auto-approved. Write scopes may require approval. Destructive scopes always require approval.`;
+Read scopes are auto-approved. Write scopes may require approval. Destructive scopes always require approval.
+
+Catching up on async actions:
+- If the user mentions a previous action ("did the Slack post go through?", "what happened to that earlier request?") OR if the previous \`use_platform\` returned a \`pending_approval\` envelope, call \`list_my_pending_actions\` to surface what's pending and what's recently completed. Tell the user the result naturally — don't dump the JSON.`;

package/package.json

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