MCP: Update Node SDK to 0.148.0

package.json

@@ -40,7 +40,7 @@
     "@modelcontextprotocol/core": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
     "@onkernel/managed-auth-react": "0.5.5",
-    "@onkernel/sdk": "0.141.0",
+    "@onkernel/sdk": "0.148.0",
     "@posthog/mcp": "0.17.0",
     "@types/jsonwebtoken": "^9.0.10",
     "@types/redis": "^4.0.11",

src/app/[transport]/route.ts

@@ -54,6 +54,7 @@ const ENTITLEMENT_GATED_TOOLS = new Set([
   "manage_vaults",
   "manage_vault_wallets",
   "manage_vault_cards",
+  "manage_vault_payment_requests",
   "manage_vault_credentials",
   "manage_vault_items",
   "manage_vault_provider_configs",

src/lib/mcp/prompts.test.ts

@@ -13,6 +13,7 @@ const BLOCKED_LANGUAGE =
 const BLOCKED_NAMES = new RegExp(`${BLOCKED_LANGUAGE.source}|captcha`, "i");
 const API_FIELD_NAMES = new Set([
   "manage_browsers:stealth",
+  "manage_browsers:fingerprint",
   "manage_browsers:captcha",
   "manage_browser_pools:stealth",
   "manage_browser_pools:captcha",

src/lib/mcp/register.test.ts

@@ -113,7 +113,8 @@ const EXPECTED_ANNOTATIONS: Record<string, [boolean, boolean, boolean]> = {
   manage_vault_items: [false, true, true],
   manage_vault_credentials: [false, true, true],
   manage_vault_cards: [false, true, true],
-  manage_vault_wallets: [false, false, true],
+  manage_vault_payment_requests: [false, true, true],
+  manage_vault_wallets: [false, true, true],
   manage_vault_provider_configs: [false, true, true],
 };
 
@@ -224,6 +225,7 @@ describe("MCP toolset allowlist", () => {
           "manage_vault_provider_configs",
           "manage_vault_wallets",
           "manage_vault_cards",
+          "manage_vault_payment_requests",
           "manage_vault_credentials",
           "manage_vault_items",
           "manage_vaults",
@@ -297,6 +299,7 @@ describe("project selection registration", () => {
     "manage_vaults",
     "manage_vault_wallets",
     "manage_vault_cards",
+    "manage_vault_payment_requests",
     "manage_vault_credentials",
     "manage_vault_items",
     "open_auth_login",

src/lib/mcp/telemetry.ts

@@ -12,4 +12,4 @@ export const telemetryEventCategories = [
   "monitor",
 ] as const;
 
-export const TELEMETRY_EVENT_CATALOG = `event categories: console (console output and uncaught exceptions), network (request/response metadata), page (navigation and lifecycle), interaction (clicks, keys, scrolls), control (agent-driven api calls), platform (KERNEL platform lifecycle and service events), connection (cdp/live-view attach/detach), system (vm health), screenshot (periodic monitor screenshots), captcha (verification prompts a site displayed during the session), monitor (telemetry collector health; captured automatically with any cdp category). high-signal event types: console_error, network_loading_failed, network_response with non-2xx status, system_oom_kill, service_crashed, monitor_disconnected (telemetry gap — treat following events as incomplete).`;
+export const TELEMETRY_EVENT_CATALOG = `event categories: console (console output and uncaught exceptions), network (request/response metadata), page (navigation and lifecycle), interaction (clicks, keys, scrolls), control (agent-driven api calls), platform (KERNEL platform lifecycle and service events), connection (cdp/live-view attach/detach), system (vm health), screenshot (periodic monitor screenshots), captcha (verification prompts a site displayed during the session), monitor (telemetry collector health; captured automatically with any cdp category). high-signal event types: console_error, network_loading_failed, network_response with non-2xx status, system_oom_kill, service_crashed, monitor_disconnected (telemetry gap — treat following events as incomplete). browser_proxy_error data.code can be payment_window_expired when the proxy reports that a payment window has expired; unrecognized proxy codes appear as unknown with the original value in raw_code.`;

src/lib/mcp/tool-contract.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import type { Tool } from "@modelcontextprotocol/server";
+import { connectTestMcp } from "@/lib/mcp/mcp-test-fixtures";
+import { registerMcpCapabilities } from "@/lib/mcp/register";
+
+// Every client loads every tool description, so long descriptions cost context on
+// each request. Per-action detail belongs in parameter descriptions or in the
+// response guidance and notes returned after a call.
+const MAX_DESCRIPTION_CHARS = 3_000;
+
+// Temporary exceptions, capped near their current size so they cannot grow. Lower
+// a cap when a description shrinks; do not raise one without moving detail out.
+const DESCRIPTION_CHAR_EXCEPTIONS: Record<string, number> = {
+  // Credential and payment safety rules (consent, secret handling, recovery) that
+  // must be read before the first call. Remaining per-provider detail should move
+  // to item guidance.
+  manage_vault_items: 10_000,
+  manage_vault_cards: 8_000,
+  manage_vault_credentials: 6_100,
+  // Reference for the helper functions available inside the repl.
+  browser_repl: 7_200,
+};
+
+// The whole tools/list payload, including input schemas, with every toolset enabled.
+const MAX_TOOLS_LIST_CHARS = 230_000;
+
+async function listAllTools() {
+  const mcp = await connectTestMcp((server) => {
+    registerMcpCapabilities(server, {
+      mcpApps: true,
+      vaults: true,
+      search: true,
+    });
+  }, {});
+  try {
+    return await mcp.client.listTools();
+  } finally {
+    await mcp.close();
+  }
+}
+
+function actionValues(tool: Tool): string[] {
+  const action = tool.inputSchema.properties?.action as
+    | { enum?: string[]; anyOf?: Array<{ enum?: string[] }> }
+    | undefined;
+  return [
+    ...(action?.enum ?? []),
+    ...(action?.anyOf ?? []).flatMap(({ enum: values }) => values ?? []),
+  ];
+}
+
+describe("tool contract", () => {
+  test("tool descriptions stay within their size budget", async () => {
+    const { tools } = await listAllTools();
+    const oversized = tools.flatMap((tool) => {
+      const limit =
+        DESCRIPTION_CHAR_EXCEPTIONS[tool.name] ?? MAX_DESCRIPTION_CHARS;
+      const length = (tool.description ?? "").length;
+      return length > limit ? [`${tool.name}: ${length} > ${limit}`] : [];
+    });
+    expect(oversized).toEqual([]);
+    for (const name of Object.keys(DESCRIPTION_CHAR_EXCEPTIONS)) {
+      expect(tools.map((tool) => tool.name)).toContain(name);
+    }
+  });
+
+  test("tools/list stays within its size budget", async () => {
+    const result = await listAllTools();
+    expect(JSON.stringify(result).length).toBeLessThanOrEqual(
+      MAX_TOOLS_LIST_CHARS,
+    );
+  });
+
+  test("tools with delete or remove actions are marked destructive", async () => {
+    const { tools } = await listAllTools();
+    const destructive = tools.filter((tool) =>
+      actionValues(tool).some(
+        (action) => action.includes("delete") || action.includes("remove"),
+      ),
+    );
+    expect(destructive.length).toBeGreaterThan(0);
+    const unmarked = destructive
+      .filter((tool) => tool.annotations?.destructiveHint !== true)
+      .map((tool) => tool.name);
+    expect(unmarked).toEqual([]);
+  });
+});

src/lib/mcp/tool-names.ts

@@ -26,6 +26,7 @@ export const KERNEL_MCP_TOOL_NAMES = [
   "manage_vault_cards",
   "manage_vault_credentials",
   "manage_vault_items",
+  "manage_vault_payment_requests",
   "manage_vault_provider_configs",
   "manage_vault_wallets",
   "manage_vaults",

src/lib/mcp/tools/api-keys.test.ts

@@ -22,6 +22,32 @@ async function callAPIKeys(apiKeys: unknown, args: Record<string, unknown>[]) {
 }
 
 describe("manage_api_keys SDK parity", () => {
+  test("advertises last-used sorting and null ordering", async () => {
+    const { client, close } = await connectTestMcp(
+      registerAPIKeyCapabilities,
+      {},
+    );
+    try {
+      const tool = (await client.listTools()).tools.find(
+        ({ name }) => name === "manage_api_keys",
+      );
+      expect(tool?.inputSchema.properties?.sort_by).toMatchObject({
+        enum: ["created_at", "name", "expires_at", "last_used_at"],
+        description: expect.stringContaining(
+          "keys missing that value sort last in either direction",
+        ),
+      });
+      expect(tool?.description).toContain(
+        "delete asynchronously ends browser sessions",
+      );
+      expect(tool?.description).toContain(
+        "grace-period or natural expiry does not end existing browsers",
+      );
+    } finally {
+      await close();
+    }
+  });
+
   test("rejects an empty api_key_id in the schema", async () => {
     let called = false;
     const [result] = await callAPIKeys(
@@ -106,7 +132,7 @@ describe("manage_api_keys SDK parity", () => {
           name: "staging",
           query: "stage",
           status: "all",
-          sort_by: "expires_at",
+          sort_by: "last_used_at",
           sort_direction: "asc",
           limit: 5,
           offset: 0,
@@ -123,7 +149,7 @@ describe("manage_api_keys SDK parity", () => {
           name: "staging",
           query: "stage",
           status: "all",
-          sort_by: "expires_at",
+          sort_by: "last_used_at",
           sort_direction: "asc",
           limit: 5,
           offset: 0,

src/lib/mcp/tools/api-keys.ts

@@ -24,7 +24,7 @@ export function registerAPIKeyCapabilities(
     "manage_api_keys",
     {
       description:
-        'manage KERNEL api keys. use "create" to create an org-wide, project-scoped, or policy-scoped key, "list" to discover masked keys, "get" to retrieve one masked key, "update" to rename a key, "rotate" to issue a replacement with an optional grace period, or "delete" to revoke a key. list and get include last_used_at, an approximate timestamp accurate within about 20 minutes; it is null when the key has not authenticated a request since last-use tracking began. create and rotate return the new plaintext key once; handle it as a secret and never repeat it in chat.',
+        'manage KERNEL api keys. use "create" to create an org-wide, project-scoped, or policy-scoped key, "list" to discover masked keys, "get" to retrieve one masked key, "update" to rename a key, "rotate" to issue a replacement with an optional grace period, or "delete" to revoke a key. list and get include last_used_at, an approximate timestamp accurate within about 20 minutes; it is null when the key has not authenticated a request since last-use tracking began. create and rotate return the new plaintext key once; handle it as a secret and never repeat it in chat. delete asynchronously ends browser sessions attributed to the revoked key and discards unsaved profile changes; if cleanup cannot be registered, deletion is not committed. rotate with expire_in_days=0 does the same immediate browser cleanup for the old key; grace-period or natural expiry does not end existing browsers, and an immediate rotation is not committed if cleanup cannot be registered.',
       inputSchema: z.object({
         action: z
           .enum(["create", "list", "get", "update", "rotate", "delete"])
@@ -115,8 +115,10 @@ export function registerAPIKeyCapabilities(
           .describe("(list) key status filter. defaults to active.")
           .optional(),
         sort_by: z
-          .enum(["created_at", "name", "expires_at"])
-          .describe("(list) field to sort by.")
+          .enum(["created_at", "name", "expires_at", "last_used_at"])
+          .describe(
+            "(list) field to sort by. when sorting by expires_at or last_used_at, keys missing that value sort last in either direction.",
+          )
           .optional(),
         sort_direction: z
           .enum(["asc", "desc"])

src/lib/mcp/tools/apps.test.ts

@@ -53,9 +53,10 @@ describe("manage_apps invocation contract", () => {
 
     try {
       const tools = await client.listTools();
-      expect(
-        tools.tools.some((tool) => tool.name === "manage_apps"),
-      ).toBeTrue();
+      const appTool = tools.tools.find((tool) => tool.name === "manage_apps");
+      expect(appTool).toBeDefined();
+      expect(appTool?.description).toContain("leased_at");
+      expect(appTool?.description).toContain("replay metadata");
 
       const result = await client.callTool({
         name: "manage_apps",
@@ -110,6 +111,7 @@ describe("manage_apps invocation contract", () => {
                 cdp_ws_url: "wss://api.onkernel.com/cdp",
                 webdriver_ws_url: "wss://api.onkernel.com/webdriver",
                 created_at: "2026-08-08T00:00:00Z",
+                leased_at: "2026-08-08T00:05:00Z",
                 headless: false,
                 stealth: true,
                 memory: "2GiB",
@@ -121,6 +123,12 @@ describe("manage_apps invocation contract", () => {
                   locale: "en-US",
                   locale_source: "override",
                 },
+                replay: {
+                  replay_id: "rpl_123",
+                  replay_view_url: "https://replay.example/view/rpl_123",
+                  started_at: "2026-08-08T00:00:01Z",
+                  finished_at: null,
+                },
               },
             ],
           };
@@ -149,12 +157,19 @@ describe("manage_apps invocation contract", () => {
             session_id: "brr_123",
             browser_live_view_url:
               "https://api.onkernel.com/browser/live/signed",
+            leased_at: "2026-08-08T00:05:00Z",
             location: {
               timezone: "America/New_York",
               timezone_source: "default",
               locale: "en-US",
               locale_source: "override",
             },
+            replay: {
+              replay_id: "rpl_123",
+              replay_view_url: "https://replay.example/view/rpl_123",
+              started_at: "2026-08-08T00:00:01Z",
+              finished_at: null,
+            },
           },
         ],
       });

src/lib/mcp/tools/apps.ts

@@ -63,7 +63,7 @@ export function registerAppCapabilities(
     "manage_apps",
     {
       description:
-        'manage KERNEL apps when an agent needs to discover deployed app actions, invoke an app, or inspect deployment/invocation state. use "list_apps" before invoking an unknown app. "invoke" starts an action asynchronously and returns an invocation_id immediately. use "list_invocations" to find runs, "list_invocation_browsers" to discover their browser sessions, and "get_invocation" after a short delay to inspect one state. do not poll indefinitely; if a run is still active, report its id. "delete_invocation_browsers" terminates every active browser created by one invocation. deployment and invocation event streams are intentionally represented by bounded list/get calls rather than an open sse stream.',
+        'manage KERNEL apps when an agent needs to discover deployed app actions, invoke an app, or inspect deployment/invocation state. use "list_apps" before invoking an unknown app. "invoke" starts an action asynchronously and returns an invocation_id immediately. use "list_invocations" to find runs, "list_invocation_browsers" to discover their browser sessions, and "get_invocation" after a short delay to inspect one state. list_invocation_browsers includes leased_at only for leased pooled sessions, showing when each was last leased, and replay metadata when recording started with the browser. do not poll indefinitely; if a run is still active, report its id. "delete_invocation_browsers" terminates every active browser created by one invocation. deployment and invocation event streams are intentionally represented by bounded list/get calls rather than an open sse stream.',
       inputSchema: z.object({
         ...projectSelectionInputSchema(),
         action: z
@@ -280,9 +280,15 @@ export function registerAppCapabilities(
               browsers: browsers.browsers.map((browser) => ({
                 session_id: browser.session_id,
                 browser_live_view_url: browser.browser_live_view_url,
+                ...(browser.leased_at !== undefined && {
+                  leased_at: browser.leased_at,
+                }),
                 ...(browser.location !== undefined && {
                   location: browser.location,
                 }),
+                ...(browser.replay !== undefined && {
+                  replay: browser.replay,
+                }),
               })),
             });
           }