@agentvalet/mcp-server 1.1.1 → 1.3.0

package/dist/net.js

@@ -0,0 +1,80 @@
+// apps/mcp-server/src/net.ts
+//
+// Stateless HTTP + MCP-content helpers. No agent identity / config state — see
+// auth.ts for the credentialed wrappers. Extracted verbatim from index.ts
+// during the modularization (Critique-Roadmap prompt 06.4); behavior unchanged.
+export function fetchWithTimeout(url, init, timeoutMs = 15_000) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    return fetch(url, { ...init, signal: ac.signal }).finally(() => clearTimeout(timer));
+}
+export function errorContent(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+// Return helper that gives an MCP-aware host the structured content directly
+// (no parse step), while still emitting the text-content envelope every MCP
+// client understands. Avoids the "list of length 1 with empty fields → let me
+// parse the wrapper" round-trip Claude does on tool results that are raw
+// JSON strings — every read-heavy use_platform call pays that cost otherwise.
+//
+// If `body` isn't valid JSON, we just return the text envelope unchanged —
+// callers that emit prose (summaries, error strings) get the old behaviour.
+export function jsonContent(body) {
+    const parsed = tryParseJson(body);
+    if (parsed === undefined) {
+        return { content: [{ type: "text", text: body }] };
+    }
+    return {
+        content: [{ type: "text", text: body }],
+        structuredContent: parsed,
+    };
+}
+export function tryParseJson(text) {
+    const trimmed = text.trim();
+    // Only attempt parse if it looks structured. Avoids parsing a stray "true"
+    // / number / etc. into structuredContent and confusing the host.
+    if (!trimmed.startsWith("{") && !trimmed.startsWith("["))
+        return undefined;
+    try {
+        const v = JSON.parse(trimmed);
+        if (v && typeof v === "object")
+            return v;
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Translates a fetch() failure into something an end-user can actually act on.
+// The default "Network error: fetch failed" message tells a non-developer
+// nothing. Look at the underlying cause keyword and map to a concrete fix.
+export function diagnoseNetworkError(err, proxyUrl) {
+    const raw = err instanceof Error ? err.message : String(err);
+    const lower = raw.toLowerCase();
+    // Node's undici surfaces DNS failures as "getaddrinfo ENOTFOUND <host>".
+    if (lower.includes("enotfound") || lower.includes("getaddrinfo")) {
+        return `Network error: cannot resolve ${proxyUrl}. Check your DNS / corporate proxy / VPN, or confirm the PROXY_URL setting is correct. Raw: ${raw}`;
+    }
+    // Connection refused / unreachable / TLS handshake failure.
+    if (lower.includes("econnrefused") || lower.includes("econnreset")) {
+        return `Network error: connection to ${proxyUrl} was refused or reset. The proxy may be down — check https://status.agentvalet.ai — or a firewall is blocking the request. Raw: ${raw}`;
+    }
+    if (lower.includes("etimedout") || lower.includes("timeout") || lower.includes("aborterror")) {
+        return `Network error: request to ${proxyUrl} timed out. Likely causes: VPN routing, corporate proxy buffering, or slow network. Try again or confirm api.agentvalet.ai is reachable from this machine. Raw: ${raw}`;
+    }
+    if (lower.includes("self signed") || lower.includes("cert") || lower.includes("ssl") || lower.includes("tls")) {
+        return `Network error: TLS / certificate problem talking to ${proxyUrl}. A corporate MITM proxy may be intercepting traffic. Raw: ${raw}`;
+    }
+    return `Network error reaching ${proxyUrl}: ${raw}. Check VPN, corporate proxy, and firewall rules for api.agentvalet.ai. If the proxy itself is down, see https://status.agentvalet.ai.`;
+}

package/dist/tools/handlers.js

@@ -0,0 +1,310 @@
+// apps/mcp-server/src/tools/handlers.ts
+//
+// The seven tool-call handlers + the approval long-poll. Extracted from
+// index.ts during the modularization (Critique-Roadmap prompt 06.4). Each
+// takes the ServerContext explicitly (config + server) instead of reaching for
+// module globals. Behavior is unchanged — pinned by test/introspection.test.ts.
+import { errorContent, jsonContent, tryParseJson, safeJsonParse, sleep, diagnoseNetworkError, fetchWithTimeout, } from "../net.js";
+import { requireCredentials, fetchWithAuth } from "../auth.js";
+export async function handleListPlatforms(ctx) {
+    const gate = await requireCredentials(ctx);
+    if (gate)
+        return gate;
+    let response;
+    try {
+        response = await fetchWithAuth(ctx, `${ctx.PROXY_URL}/v1/agent/permissions`, { method: "GET", headers: {} });
+    }
+    catch (err) {
+        return errorContent(diagnoseNetworkError(err, ctx.PROXY_URL));
+    }
+    const body = await response.text();
+    if (!response.ok)
+        return errorContent(`Proxy error ${response.status}: ${body}`);
+    // Proxy wraps the payload as { data: { platforms, version }, _meta: {...} }
+    // but outputSchema declares the flat { platforms, version } shape, so the
+    // wrapped envelope fails strict structuredContent validation and the host
+    // surfaces "tool execution failed (no upstream body)". Unwrap .data.
+    const parsed = tryParseJson(body);
+    const inner = parsed && typeof parsed === "object" && parsed !== null && "data" in parsed
+        ? parsed.data
+        : parsed;
+    if (inner && typeof inner === "object") {
+        return {
+            content: [{ type: "text", text: body }],
+            structuredContent: inner,
+        };
+    }
+    return jsonContent(body);
+}
+// 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;
+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,
+        method: params.method,
+        scope: params.scope,
+        ...(params.data !== undefined && { data: params.data }),
+        ...(params.connection_id ? { connection_id: params.connection_id } : {}),
+    };
+    let response;
+    try {
+        response = await fetchWithAuth(ctx, `${ctx.PROXY_URL}/v1/actions`, {
+            method: "POST",
+            body: JSON.stringify(requestBody),
+        });
+    }
+    catch (err) {
+        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(ctx, approvalId, params, progressToken);
+        }
+    }
+    if (!response.ok)
+        return errorContent(`Proxy error ${response.status}: ${body}`);
+    return jsonContent(body);
+}
+async function waitForApproval(ctx, approvalId, originalCall, progressToken) {
+    const startedAt = Date.now();
+    let lastProgressAt = 0;
+    // Initial progress so the user sees activity immediately.
+    await sendProgress(ctx, 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(ctx, `${ctx.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;
+            // 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)}`);
+            }
+            // Two-channel return: the text envelope carries the human-readable
+            // "[Owner approved after Ns]" prefix (visible to non-structured-aware
+            // clients), and structuredContent carries the parsed upstream JSON
+            // directly so MCP-aware hosts (Claude Desktop ≥ MCP spec 2025-06-18)
+            // never have to strip-the-prefix-and-reparse. Without the second
+            // channel the prefix forces Claude into the same wrapper-parse
+            // round-trip the bare /v1/actions path used to.
+            const data = r.data ?? null;
+            const summary = `[Owner approved after ${Math.round(elapsed / 1000)}s]\n` +
+                JSON.stringify(data);
+            const result = {
+                content: [{ type: "text", text: summary }],
+            };
+            if (data && typeof data === "object" && !Array.isArray(data)) {
+                result.structuredContent = data;
+            }
+            return result;
+        }
+        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(ctx, 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 jsonContent(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).`,
+    }));
+}
+async function sendProgress(ctx, token, progress, total, message) {
+    if (token === undefined)
+        return;
+    try {
+        await ctx.server.notification({
+            method: "notifications/progress",
+            params: { progressToken: token, progress, total, message },
+        });
+    }
+    catch {
+        // Best-effort — never let a failed notification break the call.
+    }
+}
+export async function handleAgentRegister(ctx, args) {
+    let response;
+    try {
+        response = await fetchWithTimeout(`${ctx.PROXY_URL}/v1/register`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(args),
+        });
+    }
+    catch (err) {
+        return errorContent(`Network error: ${err instanceof Error ? err.message : err}`);
+    }
+    const body = await response.text();
+    if (!response.ok)
+        return errorContent(`Proxy error ${response.status}: ${body}`);
+    return jsonContent(body);
+}
+export async function handleAgentStatus(ctx, token) {
+    let response;
+    try {
+        response = await fetchWithTimeout(`${ctx.PROXY_URL}/v1/register/status/${encodeURIComponent(token)}`, {
+            method: "GET",
+            headers: { "Content-Type": "application/json" },
+        });
+    }
+    catch (err) {
+        return errorContent(`Network error: ${err instanceof Error ? err.message : err}`);
+    }
+    const body = await response.text();
+    if (!response.ok)
+        return errorContent(`Proxy error ${response.status}: ${body}`);
+    return jsonContent(body);
+}
+export async function handleAuthzenEvaluate(ctx, platformId, scope) {
+    const gate = await requireCredentials(ctx);
+    if (gate)
+        return gate;
+    const authzenBody = {
+        subject: { type: "agent", id: ctx.AGENT_ID },
+        action: { name: "tool_call" },
+        resource: { type: "platform_scope", id: `${platformId}:${scope}` },
+    };
+    let response;
+    try {
+        response = await fetchWithAuth(ctx, `${ctx.PROXY_URL}/v1/authzen/access`, {
+            method: "POST",
+            body: JSON.stringify(authzenBody),
+        });
+    }
+    catch (err) {
+        return errorContent(`Network error: ${err instanceof Error ? err.message : err}`);
+    }
+    const body = await response.text();
+    if (!response.ok)
+        return errorContent(`Proxy error ${response.status}: ${body}`);
+    return jsonContent(body);
+}
+export async function handleListMyPendingActions(ctx) {
+    const gate = await requireCredentials(ctx);
+    if (gate)
+        return gate;
+    let response;
+    try {
+        response = await fetchWithAuth(ctx, `${ctx.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 jsonContent(text);
+}
+export async function handleReportSelfDiagnostic(ctx, args) {
+    const gate = await requireCredentials(ctx);
+    if (gate)
+        return gate;
+    // Whitelist body fields — never forward owner_id/agent_id (proxy derives those from JWT).
+    const body = {
+        severity: args.severity,
+        message: args.message,
+    };
+    for (const k of ["code", "platform", "endpoint", "correlation_id", "context"]) {
+        if (args[k] !== undefined)
+            body[k] = args[k];
+    }
+    let response;
+    try {
+        response = await fetchWithAuth(ctx, `${ctx.PROXY_URL}/v1/agents/self/diagnostics`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+    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);
+}

package/dist/tools/schemas.js

@@ -0,0 +1,272 @@
+// apps/mcp-server/src/tools/schemas.ts
+//
+// MCP tool definitions (name + description + input/output JSON schema). Pure
+// data — extracted verbatim from index.ts during the modularization
+// (Critique-Roadmap prompt 06.4). The tool SURFACE is contract-pinned by
+// test/introspection.test.ts, so any accidental change here fails CI.
+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, connections? }], version: \"<hex>\" }. A platform includes `connections` only when it has 2+ usable accounts; pass the chosen connection_id to use_platform (omit for the default).\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: {} },
+    outputSchema: {
+        type: "object",
+        properties: {
+            platforms: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        platformId: { type: "string" },
+                        platformName: { type: "string" },
+                        scopes: { type: "array", items: { type: "string" } },
+                        requireApproval: { type: "boolean" },
+                        connections: {
+                            type: "array",
+                            description: "Present only when this platform has 2+ usable connections (e.g. two GitHub orgs). Pass the chosen connection_id to use_platform; omit to use the default connection.",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    connection_id: { type: "string" },
+                                    label: { type: "string" },
+                                    is_default: { type: "boolean" },
+                                    scopes: { type: "array", items: { type: "string" } },
+                                },
+                                required: ["connection_id", "label"],
+                            },
+                        },
+                    },
+                    required: ["platformId", "platformName", "scopes"],
+                },
+            },
+            version: { type: "string" },
+        },
+        required: ["platforms"],
+    },
+};
+export const USE_PLATFORM_TOOL = {
+    name: "use_platform",
+    description: "use_platform: Call an external platform API (Airtable, GitHub, Slack, Metabase, etc.) through the AgentValet proxy.\nInput: platform (string), endpoint (string), method (GET|POST|PUT|PATCH|DELETE), scope (string), body (object, optional — JSON request body for POST/PUT/PATCH/DELETE).\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.\nNote: legacy clients passing `data` instead of `body` are still accepted for backwards compatibility, but `body` is the canonical name.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            platform: {
+                type: "string",
+                description: "Platform ID (e.g. airtable, github, slack, metabase)",
+            },
+            endpoint: {
+                type: "string",
+                description: "API path on the target platform (e.g. /v0/meta/bases or /api/dataset)",
+            },
+            method: {
+                type: "string",
+                enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+                description: "HTTP method to use",
+            },
+            scope: {
+                type: "string",
+                description: "Permission scope required for this action (e.g. records:read)",
+            },
+            body: {
+                type: "object",
+                description: "JSON request body for POST/PUT/PATCH/DELETE. Optional. Forwarded verbatim to the upstream API.",
+            },
+            data: {
+                type: "object",
+                description: "Deprecated alias for `body` — prefer `body`. Kept for backwards compatibility.",
+            },
+            connection_id: {
+                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.",
+            },
+        },
+        required: ["platform", "endpoint", "method", "scope"],
+    },
+};
+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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            owner_id: {
+                type: "string",
+                description: "The owner ID to register this agent under",
+            },
+            agent_name: {
+                type: "string",
+                description: "Human-readable name for this agent",
+            },
+            requested_scopes: {
+                type: "array",
+                description: "Array of platform scope requests",
+                items: {
+                    type: "object",
+                    properties: {
+                        platformId: { type: "string" },
+                        scopes: { type: "array", items: { type: "string" } },
+                    },
+                    required: ["platformId", "scopes"],
+                },
+            },
+        },
+        required: ["owner_id", "agent_name", "requested_scopes"],
+    },
+    outputSchema: {
+        type: "object",
+        properties: {
+            registration_token: { type: "string" },
+            poll_url: { type: "string" },
+            client_id: { type: "string" },
+            scope: { type: "string" },
+            expires_in: { type: "number" },
+        },
+        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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            token: {
+                type: "string",
+                description: "Registration token returned by agent_register",
+            },
+        },
+        required: ["token"],
+    },
+    outputSchema: {
+        type: "object",
+        properties: {
+            status: { type: "string", enum: ["pending_approval", "approved", "rejected"] },
+            agent_id: { type: "string" },
+            mcp_config: { type: "object" },
+        },
+        required: ["status"],
+    },
+};
+export const AUTHZEN_EVALUATE_TOOL = {
+    name: "authzen_evaluate",
+    description: "authzen_evaluate: Evaluate whether this agent has access to a specific platform scope. Call this BEFORE use_platform when you want to pre-check without making the upstream call.\nInput: platform_id (string), scope (string).\nReturns: decision (boolean), reason (\"approved\"|\"denied\"|\"revoked\"|\"scope_not_granted\").\nAuth: Bearer agent JWT (sent automatically by this MCP server).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            platform_id: {
+                type: "string",
+                description: "The platform identifier (e.g. airtable, github)",
+            },
+            scope: {
+                type: "string",
+                description: "The permission scope to evaluate (e.g. records:read)",
+            },
+        },
+        required: ["platform_id", "scope"],
+    },
+    outputSchema: {
+        type: "object",
+        properties: {
+            decision: { type: "boolean" },
+            context: { type: "object", properties: { reason: { type: "string" } } },
+        },
+        required: ["decision"],
+    },
+};
+export const REPORT_SELF_DIAGNOSTIC_TOOL = {
+    name: "report_self_diagnostic",
+    description: "report_self_diagnostic: Lodge a self-report (error/warning/info) with the AgentValet owner. Use after a use_platform error returns a report_hint, OR proactively when you encounter a problem the user should know about.\nInput: severity (debug|info|warn|error|critical), message (string, required, max 4096 bytes), code (string, optional, max 128 chars), platform (string, optional), endpoint (string, optional), correlation_id (uuid string, optional — copy from the failing call's report_hint to stitch this report to the broker-side audit row), context (object, optional, JSON-serialised must be < 16 KiB).\nReturns: { id, received_at } on success.\nAuth: Bearer agent JWT (sent automatically).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            severity: {
+                type: "string",
+                enum: ["debug", "info", "warn", "error", "critical"],
+                description: "Severity level. error/critical trigger an owner notification.",
+            },
+            message: {
+                type: "string",
+                description: "One-sentence agent narrative describing what happened.",
+            },
+            code: {
+                type: "string",
+                description: "Optional short machine code (e.g. 'permission_denied').",
+            },
+            platform: {
+                type: "string",
+                description: "Optional platform id this report relates to.",
+            },
+            endpoint: {
+                type: "string",
+                description: "Optional endpoint that failed.",
+            },
+            correlation_id: {
+                type: "string",
+                description: "Optional UUID — copy from a use_platform error's report_hint to stitch this report to the audit row.",
+            },
+            context: {
+                type: "object",
+                description: "Optional structured context (request params, error details). Avoid secrets.",
+            },
+        },
+        required: ["severity", "message"],
+    },
+    outputSchema: {
+        type: "object",
+        properties: {
+            id: { type: "string" },
+            received_at: { type: "string" },
+        },
+        required: ["id"],
+    },
+};
+export 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: {} },
+    outputSchema: {
+        type: "object",
+        properties: {
+            pending: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        approval_id: { type: "string" },
+                        platform_id: { type: "string" },
+                        scope: { type: "string" },
+                        created_at: { type: "string" },
+                        expires_at: { type: "string" },
+                    },
+                    required: ["approval_id", "platform_id", "scope"],
+                },
+            },
+            recently_completed: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        approval_id: { type: "string" },
+                        platform_id: { type: "string" },
+                        scope: { type: "string" },
+                        status: { type: "string" },
+                        executed_at: { type: "string" },
+                        result_summary: { type: "string" },
+                        execution_error: { type: "string" },
+                    },
+                    required: ["approval_id", "status"],
+                },
+            },
+        },
+        required: ["pending", "recently_completed"],
+    },
+};
+export const ALL_TOOLS = [
+    LIST_PLATFORMS_TOOL,
+    USE_PLATFORM_TOOL,
+    AGENT_REGISTER_TOOL,
+    AGENT_STATUS_TOOL,
+    AUTHZEN_EVALUATE_TOOL,
+    REPORT_SELF_DIAGNOSTIC_TOOL,
+    LIST_MY_PENDING_ACTIONS_TOOL,
+];