Release v0.21.0

Origin-SHA: 7e9761a4a316bd5a8167be67a5ad4f5d8f2f8dc9

Author: CodySearsOS

CHANGELOG.md

@@ -1,5 +1,17 @@
 # @opensea/tool-sdk
 
+## 0.21.0
+
+### Minor Changes
+
+- 6c1be9c: `createToolHandler` now fires the usage report through a platform `waitUntil` (keep-alive-after-response) when one is available, instead of awaiting it inline. This removes reporting latency from every successful call and closes a billing edge case: because x402 settlement runs before the report, awaiting the report meant a function freeze in that window could charge a paid caller without returning a result. With `waitUntil` the response flushes first and the report runs after.
+
+  It's automatic for most tools: the Vercel request-context `waitUntil` is auto-detected (no dependency on `@vercel/functions`), and `toCloudflareHandler` now wires the per-request `ctx.waitUntil` (its `fetch` signature gains the optional `ctx` argument). A new optional `waitUntil` option on `ToolHandlerConfig` lets you override detection or support another runtime. When no `waitUntil` is available (long-running servers, or serverless lacking it), the report is awaited as before so it still fires before any freeze.
+
+### Patch Changes
+
+- 09f20a7: The `init` Vercel template now sets `export const maxDuration = 60` on the tool entrypoint. Tools that call an LLM or other slow upstream routinely exceed Vercel's 10s Hobby default, which returns a 502 to the caller; because x402 settlement runs after the handler succeeds, a timeout in the settle/report window can also charge the caller without returning a result. 60s is the Hobby maximum and valid on Pro/Enterprise.
+
 ## 0.20.1
 
 ### Patch Changes

examples/wallet-personality-tool/api/index.ts

@@ -27,6 +27,10 @@ const vercelHandler = toVercelHandler(
   buildToolHandler({ manifest, gates: [paywall.gate] }),
 )
 
+// The LLM persona synthesis can take longer than the Hobby default (10s);
+// allow up to the Hobby maximum so slow generations don't 502 (gateway timeout).
+export const maxDuration = 60
+
 export default function (req: VercelRequest, res: VercelResponse) {
   return vercelHandler(req, res)
 }

examples/wallet-personality-tool/api/subscriber.ts

@@ -42,6 +42,10 @@ const manifest = buildSubscriberManifest({
 })
 const vercelHandler = toVercelHandler(buildToolHandler({ manifest, gates }))
 
+// The LLM persona synthesis can take longer than the Hobby default (10s);
+// allow up to the Hobby maximum so slow generations don't 502 (gateway timeout).
+export const maxDuration = 60
+
 export default function (req: VercelRequest, res: VercelResponse) {
   return vercelHandler(req, res)
 }

examples/wallet-personality-tool/src/personality.ts

@@ -8,7 +8,7 @@ import {
   type WalletDigest,
 } from "./schemas.js"
 
-const DEFAULT_MODEL = "claude-sonnet-4-6"
+const DEFAULT_MODEL = "claude-haiku-4-5"
 
 export interface SynthesizePersonalityOptions {
   /** Override the model. Falls back to env, then DEFAULT_MODEL. */

package.json

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

src/__tests__/handler.test.ts

@@ -5,6 +5,7 @@ import { extractSettlementTxHash } from "../lib/client/x402-payment.js"
 import { createToolHandler } from "../lib/handler/index.js"
 import type { ManifestDefinition } from "../lib/manifest/index.js"
 import type { Eip3009UsageReporterConfig } from "../lib/usage/eip3009-reporter.js"
+import { createEip3009UsageReporter } from "../lib/usage/eip3009-reporter.js"
 import type { GateMiddleware, InvocationEvent } from "../types.js"
 
 vi.mock("../lib/usage/eip3009-reporter.js", () => ({
@@ -284,6 +285,54 @@ describe("createToolHandler", () => {
     expect(extractSettlementTxHash(response)).toBeUndefined()
   })
 
+  it("returns the response via waitUntil without awaiting the report", async () => {
+    // A report that stays pending until we release it, so we can prove the
+    // handler returns the response before the report settles.
+    let releaseReport: () => void = () => {}
+    const reportSettled = vi.fn()
+    const pendingReport = new Promise<void>(resolve => {
+      releaseReport = () => {
+        reportSettled()
+        resolve()
+      }
+    })
+    vi.mocked(createEip3009UsageReporter).mockReturnValueOnce(
+      vi.fn().mockReturnValue(pendingReport),
+    )
+
+    const registered: Promise<unknown>[] = []
+    const waitUntil = vi.fn((p: Promise<unknown>) => {
+      registered.push(p)
+    })
+    const handler = createToolHandler({
+      manifest: testManifest,
+      inputSchema: InputSchema,
+      outputSchema: OutputSchema,
+      usageReporting: {} as Eip3009UsageReporterConfig,
+      waitUntil,
+      handler: async input => ({ result: `Echo: ${input.query}` }),
+    })
+    const request = new Request("https://test.example.com/api", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ query: "test" }),
+    })
+
+    const response = await handler(request)
+
+    expect(response.status).toBe(200)
+    // The report was handed to waitUntil, not awaited: the response resolved
+    // while the report is still pending.
+    expect(waitUntil).toHaveBeenCalledOnce()
+    expect(registered[0]).toBeInstanceOf(Promise)
+    expect(reportSettled).not.toHaveBeenCalled()
+
+    // Releasing it completes the backgrounded report.
+    releaseReport()
+    await registered[0]
+    expect(reportSettled).toHaveBeenCalledOnce()
+  })
+
   it("does not call settle() when a gate short-circuits with a response", async () => {
     const settle = vi.fn()
     const gate: GateMiddleware = {

src/lib/adapters/cloudflare.ts

@@ -1,16 +1,32 @@
 import type { ToolHandlerConfig } from "../handler/index.js"
 import { createToolHandler } from "../handler/index.js"
 
+/** Minimal shape of the Cloudflare Workers `ExecutionContext`. */
+interface CloudflareExecutionContext {
+  waitUntil?: (promise: Promise<unknown>) => void
+}
+
 interface CloudflareWorkerExportedHandler {
-  fetch: (request: Request, env: Record<string, string | undefined>) => Promise<Response>
+  fetch: (
+    request: Request,
+    env: Record<string, string | undefined>,
+    ctx?: CloudflareExecutionContext,
+  ) => Promise<Response>
 }
 
 export function toCloudflareHandler<TIn, TOut>(
   config: Omit<ToolHandlerConfig<TIn, TOut>, "env">,
 ): CloudflareWorkerExportedHandler {
   return {
-    fetch: (request, env) => {
-      const handler = createToolHandler({ ...config, env })
+    fetch: (request, env, ctx) => {
+      // Wire the per-request `ctx.waitUntil` so the fire-and-forget usage
+      // report runs as keep-alive-after-response work rather than blocking the
+      // response (or being killed at flush). An explicit `config.waitUntil`
+      // still wins.
+      const waitUntil =
+        config.waitUntil ??
+        (ctx?.waitUntil ? ctx.waitUntil.bind(ctx) : undefined)
+      const handler = createToolHandler({ ...config, env, waitUntil })
       return handler(request)
     },
   }

src/lib/handler/index.ts

@@ -11,6 +11,44 @@ import type { Eip3009UsageReporterConfig } from "../usage/eip3009-reporter.js"
 import { createEip3009UsageReporter } from "../usage/eip3009-reporter.js"
 import { ToolHandlerError } from "./error.js"
 
+type WaitUntil = (promise: Promise<unknown>) => void
+
+/**
+ * Best-effort detection of a platform "keep-alive after response" primitive,
+ * so fire-and-forget usage reports fire reliably without the tool author
+ * wiring anything. Returns `undefined` when none is available (the caller
+ * then awaits the report instead).
+ *
+ * Vercel populates a request-context global (the same one `@vercel/functions`
+ * reads) holding a `waitUntil`. We read it directly to avoid a hard dependency
+ * on `@vercel/functions`. Cloudflare's `ctx.waitUntil` is per-request and is
+ * wired by `toCloudflareHandler` (passed via the `waitUntil` config option),
+ * so it isn't detected here.
+ *
+ * Reading a global symbol is an accepted, bounded risk: anything could shadow
+ * it, so we only trust it when it resolves to a callable `waitUntil` (the
+ * `typeof === "function"` guard below) and otherwise fall back to awaiting the
+ * report. The exposure is no worse than depending on `@vercel/functions`, which
+ * reads the same global.
+ */
+function detectPlatformWaitUntil(): WaitUntil | undefined {
+  try {
+    const store = (
+      globalThis as Record<symbol, unknown>
+    )[Symbol.for("@vercel/request-context")] as
+      | { get?: () => { waitUntil?: WaitUntil } | undefined }
+      | undefined
+    const ctx = store?.get?.()
+    if (typeof ctx?.waitUntil === "function") {
+      // Call through `ctx` to preserve `this` binding.
+      return (promise) => ctx.waitUntil?.(promise)
+    }
+  } catch {
+    // Detection is best-effort; fall back to awaiting the report.
+  }
+  return undefined
+}
+
 export interface ToolHandlerConfig<TIn, TOut> {
   manifest: ManifestDefinition
   env?: Record<string, string | undefined>
@@ -34,6 +72,20 @@ export interface ToolHandlerConfig<TIn, TOut> {
    * analytics or rate limiting. Errors are caught and logged.
    */
   onInvocation?: (event: InvocationEvent) => void | Promise<void>
+  /**
+   * Platform "keep-alive after response" primitive (e.g. Vercel/Cloudflare
+   * `waitUntil`). When available, the fire-and-forget usage report is
+   * registered through it and the response is returned without awaiting the
+   * report — so reporting never adds latency and a function freeze in the
+   * report window can't leave a paid caller charged with no result.
+   *
+   * Usually you don't set this: it's auto-detected from the Vercel request
+   * context, and `toCloudflareHandler` wires `ctx.waitUntil` for you. Pass it
+   * explicitly only to override detection or to support another runtime. When
+   * no `waitUntil` is available (long-running servers, or serverless without
+   * it), the report is awaited instead so it still fires before the freeze.
+   */
+  waitUntil?: (promise: Promise<unknown>) => void
 }
 
 export function createToolHandler<TIn, TOut>(
@@ -148,17 +200,27 @@ export function createToolHandler<TIn, TOut>(
         }
       }
 
-      // 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.
+      // Fire the usage report. The reporter has its own AbortController
+      // timeout (default 5s) and never throws; the catch is belt-and-suspenders.
+      //
+      // With a platform `waitUntil` (auto-detected, or supplied via config /
+      // `toCloudflareHandler`), register the report as keep-alive-after-response
+      // work and return immediately — reporting adds no latency, and because the
+      // response flushes before the report runs, a freeze in the report window
+      // can't leave a paid caller charged with no result. Without `waitUntil`
+      // (long-running servers, or serverless lacking it), await instead: on a
+      // frozen runtime a fire-and-forget report would be killed at flush and
+      // never arrive.
       if (usageReporter) {
-        await usageReporter(event).catch((err) => {
+        const reportPromise = usageReporter(event).catch((err) => {
           console.error("[tool-sdk] usageReporting failed:", err)
         })
+        const waitUntil = config.waitUntil ?? detectPlatformWaitUntil()
+        if (waitUntil) {
+          waitUntil(reportPromise)
+        } else {
+          await reportPromise
+        }
       }
 
       // When the call was paid and settled onchain, echo the settlement tx

src/templates/vercel/api/index.ts

@@ -7,6 +7,14 @@ import { toolHandler } from "../src/handler.js"
 
 const handler = toVercelHandler(toolHandler)
 
+// Raise the function timeout above Vercel's 10s Hobby default. Tools that call
+// an LLM or other slow upstream can exceed 10s, which returns a 502 to the
+// caller. Worse, x402 settlement runs after your handler succeeds, so a kill
+// in the settle/report window can charge the caller without returning a result.
+// 60s is the Hobby maximum and is valid on Pro/Enterprise too. Lower it if your
+// tool is fast, or raise it on paid plans.
+export const maxDuration = 60
+
 export default function (req: VercelRequest, res: VercelResponse) {
   return handler(req, res)
 }