wave-ask

Skill: wave-ask / wave_compose

wave_compose is the registered successor to wave.ask (mcp-server PR4-MCP). It takes the same kind of input and, when a WAVE_API_KEY is configured, also tries the live gateway POST /v1/compose route first (grounding: "gateway"), falling back to exactly the composition logic documented below (grounding: "snapshot") when no key is set or the live call fails, errors, or times out after 3 seconds. wave.ask is kept, unchanged, as an offline-only alias for one release — everything below applies to both, except wave_compose's input field is intent (not question) and its output additionally carries grounding.

When to use

An agent has a media-processing goal (captions, clips, dub, identity, x402 rails) and wants the WAVE product/MCP tool/price shape for it before calling. "Identity" resolves via the real identity_resolve MCP tool only — no dedicated identity product exists in the catalog yet, so its proposal's productIds is empty by design, never a fabricated id.

When NOT to use

Already know the route — call it directly. Need the full contract — read https://api.wave.online/openapi.json or this server's live tools/list listing instead.

How to call

MCP: wave_compose({ intent: "<goal>", budgetUsd?: <number> }) — registered alongside every other tool in this package's src/tools/index.ts. (The deprecated wave.ask({ question: "<goal>", budgetUsd?: <number> }) alias still works identically for one release.)

{ "intent": "live captions from my mic" }

budgetUsd is optional and never used to compute or invent a price — it only reorders which suggestion in next[] is surfaced first (a reminder to confirm the live 402 quote against it before calling).

What you get back

A proposal object:

{
  "intent": "live captions from my mic",
  "stages": ["realtime", "transcribe", "captions"],
  "productIds": ["realtime", "transcribe", "captions"],
  "tools": ["perception_subscribe", "wave_create_caption_job", "wave_list_captions", "wave_download_captions"],
  "meters": ["wave_realtime_video_minutes", "wave_transcription_minutes", "wave_caption_minutes"],
  "priceRows": [
    { "productId": "realtime", "meter": "wave_realtime_video_minutes", "priceShape": "x402 · USDC · base", "quote": "quote at call time" },
    { "productId": "transcribe", "meter": "wave_transcription_minutes", "priceShape": "x402 · USDC · base", "quote": "quote at call time" },
    { "productId": "captions", "meter": "wave_caption_minutes", "priceShape": "x402 · USDC · base", "quote": "quote at call time" }
  ],
  "executes": false,
  "next": [
    "adjacent capability: translated captions in a second language",
    "agent path via MCP: call perception_subscribe directly once you're ready to execute this yourself",
    "saved-flow signup: keep this composition for next time (post-GA)"
  ],
  "grounding": "snapshot"
}