Release v0.14.2

Origin-SHA: e6e7921206f16bd682632e00653f174f0eff332f

Author: CodySearsOS

CHANGELOG.md

@@ -1,5 +1,13 @@
 # @opensea/tool-sdk
 
+## 0.14.2
+
+### Patch Changes
+
+- d7c1191: Await the `usageReporting` reporter before returning the tool response.
+
+  Previously the handler fired the reporter fire-and-forget after the response was built. On serverless runtimes (Vercel, AWS Lambda) the function is frozen the moment the response flushes, which killed the in-flight request so the usage report silently never arrived. The handler now awaits the report (bounded by the reporter's `timeoutMs`, default 5s) so it reliably completes; failures are still caught and logged and never fail the tool call.
+
 ## 0.14.1
 
 ### Patch Changes

README.md

@@ -876,7 +876,7 @@ const handler = createToolHandler({
 
 > **Reporting is the service's job, never the caller's.** The `apiKey` authenticates *you* (the operator) as the reporter. The caller is identified by data they already supplied (the x402 payer, or the EIP-3009 authorization `predicateGate` verified), so no caller wallet, signing, or `walletClient` is involved.
 
-That's it: the handler fires the reporter as a fire-and-forget async call at the very end of the lifecycle, after the response is built. It never blocks or fails the tool call.
+That's it: the handler runs the reporter at the very end of the lifecycle, after the output is computed and gates have settled. It is **awaited** before the response is returned (bounded by the reporter's `timeoutMs`, default 5s) so the report reliably completes even on serverless runtimes that freeze the function the moment the response flushes. Reporter failures are caught and logged; they never fail the tool call.
 
 ### How it works
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/tool-sdk",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "type": "module",
   "description": "SDK and CLI for building ERC-8257 compliant AI agent tools",
   "repository": {

skill/SKILL.md

@@ -381,7 +381,7 @@ Tool-sdk reports usage to OpenSea's analytics endpoint (`POST /api/v2/tools/usag
 
 ### usageReporting (recommended)
 
-Pass `usageReporting` to `createToolHandler` and it fires the reporter as a fire-and-forget call at the very end of the lifecycle (after the response is built). No `walletClient` is needed server-side:
+Pass `usageReporting` to `createToolHandler` and it runs the reporter at the very end of the lifecycle, awaited before the response returns (bounded by `timeoutMs`, default 5s) so it completes even on serverless runtimes that freeze on response flush. Failures are logged, never fatal. No `walletClient` is needed server-side:
 
 - **Paid x402 calls** → `verification_type: "x402_settlement"` with the payer address and settlement tx hash. The backend verifies the tx directly.
 - **EIP-3009-authenticated calls** (behind `predicateGate`) → `verification_type: "eip3009_authorization"`, **forwarding the caller's original signed authorization**. The caller already signed it to authenticate, so the reported identity is the real caller.

src/__tests__/handler.test.ts

@@ -489,7 +489,7 @@ describe("createToolHandler", () => {
     expect(order).toEqual(["handler", "settle", "onInvocation"])
   })
 
-  it("fires usageReporting as fire-and-forget on successful invocation", async () => {
+  it("fires usageReporting on successful invocation", async () => {
     const { createEip3009UsageReporter } = await import(
       "../lib/usage/eip3009-reporter.js"
     )
@@ -522,45 +522,57 @@ describe("createToolHandler", () => {
     )
     expect(response.status).toBe(200)
 
-    // flush fire-and-forget microtask
-    await vi.waitFor(() => expect(mockReporter).toHaveBeenCalledOnce())
+    // Awaited before the response resolves — no waitFor needed.
+    expect(mockReporter).toHaveBeenCalledOnce()
     const event: InvocationEvent = mockReporter.mock.calls[0]![0]
     expect(event.paid).toBe(false)
     expect(event.latencyMs).toBeGreaterThanOrEqual(0)
   })
 
-  it("fires usageReporting after response is built", async () => {
+  it("awaits usageReporting before returning the response", async () => {
+    // Regression guard: on serverless the function freezes once the response
+    // flushes, so the report must complete *before* the handler resolves, not
+    // fire-and-forget after.
     const { createEip3009UsageReporter } = await import(
       "../lib/usage/eip3009-reporter.js"
     )
-    let reporterCalledBeforeReturn = false
-    const mockReporter = vi.fn().mockResolvedValue(undefined)
-    vi.mocked(createEip3009UsageReporter).mockReturnValue(mockReporter)
-    const onInvocation = vi.fn(() => {
-      reporterCalledBeforeReturn = mockReporter.mock.calls.length > 0
+    let releaseReport: () => void = () => {}
+    const reportGate = new Promise<void>(resolve => {
+      releaseReport = resolve
     })
+    const mockReporter = vi.fn(() => reportGate)
+    vi.mocked(createEip3009UsageReporter).mockReturnValue(mockReporter)
 
     const handler = createToolHandler({
       manifest: testManifest,
       inputSchema: InputSchema,
       outputSchema: OutputSchema,
       handler: async input => ({ result: `Echo: ${input.query}` }),
       usageReporting: {} as unknown as Eip3009UsageReporterConfig,
-      onInvocation,
     })
 
-    const response = await handler(
+    let settled = false
+    const pending = handler(
       new Request("https://test.example.com/api", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ query: "test" }),
       }),
-    )
+    ).then(res => {
+      settled = true
+      return res
+    })
+
+    // Let all of the handler's own awaits drain. The report promise is still
+    // pending, so the handler must not have resolved.
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(mockReporter).toHaveBeenCalledOnce()
+    expect(settled).toBe(false)
+
+    releaseReport()
+    const response = await pending
+    expect(settled).toBe(true)
     expect(response.status).toBe(200)
-    expect(onInvocation).toHaveBeenCalledOnce()
-    // onInvocation runs before usageReporting (which is fire-and-forget)
-    expect(reporterCalledBeforeReturn).toBe(false)
-    await vi.waitFor(() => expect(mockReporter).toHaveBeenCalledOnce())
   })
 
   it("logs usageReporting errors without affecting the response", async () => {

src/lib/handler/index.ts

@@ -147,15 +147,20 @@ export function createToolHandler<TIn, TOut>(
         }
       }
 
-      const response = Response.json(outputResult.data, { status: 200 })
-
+      // Await the report so it completes before the response is returned.
+      // On serverless runtimes (Vercel/AWS Lambda) the function is frozen
+      // once the response flushes, which kills any fire-and-forget request
+      // still in flight — the report would silently never arrive. The
+      // reporter has its own AbortController timeout (default 5s) and never
+      // throws; the catch is belt-and-suspenders so a misbehaving reporter
+      // can never turn a successful tool call into a failure.
       if (usageReporter) {
-        void usageReporter(event).catch((err) => {
+        await usageReporter(event).catch((err) => {
           console.error("[tool-sdk] usageReporting failed:", err)
         })
       }
 
-      return response
+      return Response.json(outputResult.data, { status: 200 })
     } catch (error) {
       if (error instanceof ToolHandlerError) {
         console.error("[tool-sdk] tool handler error:", error)