vent-hq 0.10.5 → 0.10.6

package/dist/index.mjs

@@ -5949,13 +5949,13 @@ import * as fs5 from "node:fs/promises";
 import * as path3 from "node:path";
 
 // src/skills/claude-code.md
-var claude_code_default = '---\nname: vent\ndescription: Place real calls against the user\'s voice agent to verify recent code changes worked end-to-end. Trigger on test requests or after any non-trivial voice-agent change.\nallowed-tools: Bash(npx vent-hq *)\n---\n\n# Vent - Voice Agent Calls\n\nUse Vent to verify real voice-agent behavior from the terminal.\n\n## When to Test\n\nVent is the voice CI gate for the agent. A non-trivial change that touches voice behavior is not "done" until the relevant Vent call has been run and you\'ve judged from its output that the change works. Auto-trigger a call after finishing the change \u2014 do not wait to be asked.\n\nNon-trivial means anything that can change what the caller hears, how the agent responds, what tools are called, how the call routes, or how audio timing behaves: prompt rewrites or sections (not a one-word tweak), tool schema or handler changes, state/memory logic, transfer logic, interruption handling, provider/audio config, platform integration code, and any bug fix for voice-agent behavior. One-line copy or comment edits do not need a call.\n\nBefore launching, check `.vent/runs/` for unresolved issues from prior runs (failing status, regressions, warnings, latency jumps). If any are still present and within the scope of the current task, fix them as part of this change, then run the call to verify both the new fix and the prior issues are resolved. Report unresolved prior issues that are out of scope rather than silently leaving them.\n\nDo not declare the task complete until you\'ve reviewed the call results \u2014 transcript, tool calls, observed behavior \u2014 and confirmed the change actually does what was intended. Vent\'s `status` and exit code only tell you whether the call ran end-to-end without a pipeline error; mission success is your judgment.\n\n## Autonomous Iteration\n\nYou can run a fix \u2192 Vent-call \u2192 fix \u2192 Vent-call loop within a single user request, doing many iterations before returning. This is genuinely useful for mechanical issues where the fix is high-confidence but the verification is slow.\n\nDefault: don\'t iterate autonomously. Run the relevant call after your change, surface findings, and let the user decide what\'s next \u2014 they stay in control of cost and scope.\n\nTrigger autonomous iteration when either:\n- The user explicitly asks for it ("iterate until it works", "keep going", "autonomous mode", "fix everything").\n- You judge it\'s clearly worth it: the change is well-scoped, the failure mode is mechanical (tool schema, registry, prompt phrasing), and you have a concrete plan for the next attempt. If you\'d be guessing at the next attempt, stop and ask.\n\nCap iterations at ~5 unless the user gave a higher bound. If the same fix attempt fails twice, or the failure mode keeps shifting between attempts, stop and report \u2014 you\'re thrashing.\n\nThe user may not know autonomous iteration is on the table. When you suspect a likely-multi-cycle issue, offer it once before starting solo (e.g. "I can iterate on this autonomously, otherwise I\'ll stop here for your review").\n\n## Claude Code Execution\n\nUse a 5-minute shell-tool timeout (`300000` ms) on Vent run commands so normal calls are not killed by the default 2-minute Bash timeout. This is not backgrounding; wait for stdout/results before ending your response. Use the JSON returned by `npx vent-hq run` directly; do not call `vent status` unless checking an older run.\n\n### Parallel Execution\n\nClaude Code serializes separate Bash tool calls for `npx vent-hq ...`, so run multiple calls from one suite by invoking each named call with `--call <name>` in one Bash command using `&` and a final `wait`.\n\n```bash\nnpx vent-hq run -f .vent/suite.vapi.json --call happy-path & \\\nnpx vent-hq run -f .vent/suite.vapi.json --call tool-path & \\\nwait\n```\n\n## Workflow\n\n1. Identify the behavior under test. Read enough of the agent codebase to understand its system prompt, tools, handlers, routes, provider config, platform wiring, and expected handoffs.\n2. Reuse an existing `.vent/suite.<adapter>.json` when possible. If `.vent/` contains multiple suites, inspect `connection.adapter` and report which suite file produced the result.\n3. Create or update a suite only when the existing calls do not cover the changed behavior. Name calls after real flows, for example `reschedule-appointment`, not `call-1`.\n4. If the suite uses `start_command`, start one shared local session first with `npx vent-hq agent start -f .vent/suite.<adapter>.json`, then pass `--session <session-id>` to each run. **For locally-run LiveKit agents: every run requires restarting the worker first, then waiting a full 60 seconds before submitting the call.** This is unconditional \u2014 every run, no exceptions. Skipping the wait fails with `did not publish audio track` even though the worker is up. Hosted LiveKit Cloud agents don\'t need this; just run normally.\n5. Pick which call(s) to run based on the change. Fixed bug: replay the failing scenario. Changed tool: include a call that triggers that tool. Prompt or routing change: include the relevant happy path and any important edge path.\n6. Compare against the previous JSON in `.vent/runs/` when validating a fix or regression. Check status flips, latency jumps, tool-call success drops, cost jumps, and transcript divergence. Correlate with `git diff` between saved `git_sha` values when available; skip if no previous run exists.\n\n## Saved Runs\n\nAfter every run, Vent writes the full result JSON to `.vent/runs/`. Shape:\n\n```jsonc\n{\n  "run_id": "...",\n  "timestamp": "2026-04-21T...Z",\n  "git_sha": "...",\n  "summary": { "calls_total": 2, "total_duration_ms": 12345, "total_cost_usd": 0.01 },\n  "call_results": [\n    { "name": "happy-path", "status": "completed", "duration_ms": 6123, "transcript": [], "observed_tool_calls": [], "metrics": { "latency_p50_ms": 420, "latency_p95_ms": 980 }, "cost_usd": 0.004 }\n  ]\n}\n```\n\nWhen comparing against a prior run (Workflow step 6), inspect these paths:\n\n- Run-completion status flips: `call_results[i].status` (this only reflects whether the call ran cleanly through the pipeline, not whether the agent accomplished the goal \u2014 judge that from the transcript)\n- Latency: `call_results[i].metrics.latency_p50_ms` or `latency_p95_ms` increased >20%\n- Tool calls: count of `call_results[i].observed_tool_calls[].successful` dropped\n- Cost: `summary.total_cost_usd` or `call_results[i].cost_usd` increased >30%\n- Transcript: `call_results[i].transcript` diverged in semantic content (ignore STT noise)\n\n## Commands\n\n```bash\nnpx vent-hq init                                                                         # First-time setup: autonomous auth, access token generation, skill install, and minimal starter suite\nnpx vent-hq login                                                                        # Log in to an existing account and save credentials\nnpx vent-hq run -f .vent/suite.<adapter>.json                                            # Run the only call in a suite, or error if the suite has multiple calls\nnpx vent-hq run -f .vent/suite.<adapter>.json --call happy-path                          # Run one named call from a multi-call suite\nnpx vent-hq run -f .vent/suite.<adapter>.json --call happy-path --session <session-id>   # Run one named call through an existing local relay session\nnpx vent-hq run -f .vent/suite.<adapter>.json --call happy-path --verbose                # Run one named call with verbose debug fields\nnpx vent-hq stop <run-id>                                                                # Cancel a queued or running run\nnpx vent-hq status <run-id>                                                              # Fetch results for a previous run\nnpx vent-hq status <run-id> --verbose                                                    # Fetch previous run results with verbose debug fields\nnpx vent-hq agent start -f .vent/suite.<adapter>.json                                    # Start a shared local relay session for suites that use start_command\nnpx vent-hq agent stop <session-id>                                                      # Stop a shared local relay session\n```\n\nIf `~/.vent/credentials` is missing and `VENT_ACCESS_TOKEN` is not set, run `npx vent-hq init`. For an existing account, run `npx vent-hq login` or set `VENT_ACCESS_TOKEN`.\n\n## Suite Config\n\nSuites live in `.vent/suite.<adapter>.json`. `connection` is declared once per suite. `calls` is a named map, and each key becomes the call name used with `--call`.\n\nLocal websocket suite:\n\n```json\n{\n  "connection": {\n    "adapter": "websocket",\n    "start_command": "npm run start",\n    "health_endpoint": "/health",\n    "agent_port": 3001\n  },\n  "calls": {\n    "happy-path": {\n      "caller_prompt": "You are Maria calling to reschedule her appointment to next Tuesday.",\n      "max_turns": 8,\n      "silence_threshold_ms": 1200,\n      "audio_actions": [\n        { "action": "interrupt", "at_turn": 3, "prompt": "Just give me the earliest one." }\n      ]\n    }\n  }\n}\n```\n\nPlatform-direct suite:\n\n```json\n{\n  "connection": {\n    "adapter": "vapi",\n    "platform": { "provider": "vapi" }\n  },\n  "calls": {\n    "happy-path": {\n      "caller_prompt": "You are Maria calling to reschedule her appointment to next Tuesday.",\n      "max_turns": 8\n    }\n  }\n}\n```\n\nWrite `caller_prompt` as a realistic caller with a name, goal, mood, constraints, and conditional behavior. Set `max_turns` based on flow complexity: FAQ `4-6`, booking or tool use `8-12`, complex flows `12-20`.\n\nCall fields:\n\n- `caller_prompt` and `max_turns` are required.\n- `silence_threshold_ms` must be `200-10000`. Common ranges: FAQ `800-1200`, tool calls `2000-3000`, complex reasoning `3000-5000`.\n- `persona` supports `pace`, `clarity`, `disfluencies`, `cooperation`, `emotion`, `interruption_style`, `memory`, `intent_clarity`, and `confirmation_style`.\n- `audio_actions` supports `interrupt`, `inject_noise`, `split_sentence`, and `noise_on_caller`.\n- `caller_audio` supports noise, speed, speakerphone, mic distance, clarity, accent, packet loss, and jitter.\n- `language` is an ISO 639-1 code such as `en`, `es`, `fr`, `de`, `it`, `nl`, or `ja`.\n- `prosody: true` enables emotion analysis and requires Hume access.\n- Prefer explicit `audio_actions.interrupt` over `persona.interruption_style` for deterministic barge-in tests. `persona.interruption_style` is only a preplanned caller tendency.\n\n## Connections and Credentials\n\n### Adapter choice\n\nUse `websocket` for your own local or hosted runtime. Use `start_command` for local agents or `agent_url` for hosted custom endpoints. For `start_command` and `agent_url`, do not put Deepgram, ElevenLabs, OpenAI, or other agent runtime keys into Vent config unless the Vent adapter itself needs them \u2014 the tested agent owns its own runtime credentials.\n\nUse `vapi`, `retell`, `elevenlabs`, `bland`, or `livekit` for platform-direct testing. In this mode Vent itself talks to the provider on the user\'s behalf.\n\nVent provides `DEEPGRAM_API_KEY` and `ANTHROPIC_API_KEY` for its hosted caller/evaluation stack \u2014 those are Vent\'s, not the tested agent\'s.\n\n### Credential resolution\n\nIn platform-direct mode the CLI auto-resolves credentials from `.env.local`, `.env`, and the current shell environment. Do not run `source .env && export` before Vent commands. If you include credential fields in JSON, use the actual value, not the env var name. Do not manually author `platform_connection_id`; the CLI creates or updates the saved platform connection automatically.\n\nAuto-resolved env vars and JSON fields:\n\n- Vapi: `VAPI_API_KEY` -> `vapi_api_key`; `VAPI_ASSISTANT_ID` or `VAPI_AGENT_ID` -> `vapi_assistant_id`\n- Bland: `BLAND_API_KEY` -> `bland_api_key`; `BLAND_PATHWAY_ID` -> `bland_pathway_id`; `BLAND_PERSONA_ID` -> `persona_id`\n- LiveKit: `LIVEKIT_API_KEY` -> `livekit_api_key`; `LIVEKIT_API_SECRET` -> `livekit_api_secret`; `LIVEKIT_URL` -> `livekit_url`\n- Retell: `RETELL_API_KEY` -> `retell_api_key`; `RETELL_AGENT_ID` -> `retell_agent_id`\n- ElevenLabs: `ELEVENLABS_API_KEY` -> `elevenlabs_api_key`; `ELEVENLABS_AGENT_ID` -> `elevenlabs_agent_id`\n\n### Provider config\n\nUse existing provider config when possible: Vapi assistant, Retell agent, ElevenLabs agent, Bland pathway, or LiveKit agent. Bland uniquely supports inline config \u2014 `platform` may use `bland_pathway_id`, `persona_id`, or an inline `task` (with optional voice, model, and turn-handling overrides; see Bland\'s API docs for the full field list).\n\n### Concurrency\n\nWhen you fan out multiple Vent calls in parallel against the same provider (for example, running several named calls from one suite at once with `&` and `wait`), respect the provider\'s per-account concurrency limit. Exceeding it makes calls queue or fail at the provider \u2014 Vent does not enforce these caps for you.\n\nRecord the limit as `max_concurrency` in the suite\'s `platform` block so it\'s visible on future runs. Ask the user which plan they\'re on if sizing matters; otherwise use the conservative default in bold.\n\n- **Vapi**: **10** included per account; reserved lines can be purchased self-serve; Enterprise is unlimited.\n- **Retell**: Pay-as-you-go includes **20**; Enterprise has no cap.\n- **Bland**: Start=**10**, Build=50, Scale=100, Enterprise=unlimited.\n- **ElevenLabs**: Free=**4**, Starter=6, Creator=10, Pro=20, Scale=30, Business=30. Burst pricing can temporarily allow up to 3x base.\n- **LiveKit Cloud**: Build=**5**, Ship=20, Scale=50 managed inference sessions (the usual gate for voice agents); agent-session concurrency can go higher (Scale up to 600).\n\n## WebSocket\n\nFor `adapter: "websocket"`, Vent sends binary 16-bit mono PCM audio over one websocket connection. Websocket text frames are optional JSON events. Audio-only websocket agents still work, but events improve turn detection and observability. Vent sends `{"type":"end-call"}` when the test is done.\n\nUseful websocket text frames:\n\n```jsonc\n{"type":"speech-update","status":"started"}\n{"type":"speech-update","status":"stopped"}\n{"type":"tool_call","name":"check_availability","arguments":{},"result":{},"successful":true,"duration_ms":150}\n{"type":"vent:timing","stt_ms":120,"llm_ms":450,"tts_ms":80}\n{"type":"vent:session","platform":"custom","provider_call_id":"call_123","provider_session_id":"session_abc"}\n{"type":"vent:call-metadata","call_metadata":{"recording_url":"https://...","cost_usd":0.12}}\n{"type":"vent:transcript","role":"caller","text":"I need to reschedule","turn_index":0}\n{"type":"vent:transfer","destination":"+15551234567","status":"attempted"}\n{"type":"vent:debug-url","label":"trace","url":"https://..."}\n{"type":"vent:warning","message":"provider warning","code":"provider_warning"}\n```\n\n`vent:session-report` is **not** handled by the websocket adapter \u2014 it\'s only consumed by the LiveKit helper. Do not emit it from a websocket agent.\n\nPlatform adapters capture tool calls automatically. Websocket agents must emit `tool_call` frames for tool observability. Platform adapters get component latency automatically. Websocket agents should emit `vent:timing` after each agent response when STT/LLM/TTS breakdown is available.\n\n## LiveKit\n\nBefore running LiveKit tests, install and add the Vent helper to the LiveKit agent entrypoint. Node: `npm install @vent-hq/livekit`, then call `instrumentLiveKitAgent({ ctx, session })`. Python: `pip install vent-livekit`, then call `instrument_livekit_agent(ctx=ctx, session=session)`.\n\nLiveKit direct mode requires the LiveKit Agents SDK. Custom LiveKit participants should use the websocket adapter with a relay. If the LiveKit agent registered with an explicit dispatch name, set `livekit_agent_name` in `platform`.\n\nLiveKit does not support multiple concurrent Vent calls against one agent process yet. Run LiveKit calls sequentially unless you intentionally start separate agent worker processes and route each call to its own process. For Node agents, that means separate Node.js processes. Do not treat parallel calls against a single LiveKit worker as a valid concurrency test until multi-call support is engineered.\n\nUse the LiveKit helper for observability; do not publish `vent:*` topics manually. Do not hand-roll `vent:session-report` from `ctx.addShutdownCallback`; after `room.disconnect()` it can fail with `engine is closed`. The helper captures SDK metrics, tool events, conversation items, usage, and close events. Native LiveKit `lk.transcription` and `lk.agent.state` provide transcript and agent-state timing.\n\nIf a LiveKit run fails with `agent did not speak` or `no speech detected`, kill the stale agent, wait 60 seconds, then restart once. Do not restart multiple times in quick succession \u2014 each restart leaves a stale registration that compounds the routing problem.\n\n## Vent Output\n\n`npx vent-hq run` returns one JSON result on stdout in non-TTY agent mode; it is not an SSE JSONL stream. Analyze that result directly. Exit codes: `0` = call ran end-to-end through the pipeline; `1` = pipeline-level failure (call did not complete cleanly); `2` = harness error. None of these is a judgment of whether the agent actually accomplished the scenario\'s goal \u2014 decide that yourself from the transcript, tool calls, and the scenario\'s expected behavior.\n\nAlways-present keys (value may be `null` for `name`/`error`, otherwise non-null): `name`, `status`, `caller_prompt`, `duration_ms`, `error`, `transcript`, `tool_calls`, `warnings`, `audio_actions`. Always-present keys with nullable value (when the underlying analysis did not run): `latency`, `component_latency`, `call_metadata`, `emotion` (requires `prosody: true`). Conditional key (absent unless requested): `debug` (only when `--verbose`). Branch on null before reading nested fields.\n\nTrigger `--verbose` when:\n- transcript accuracy looks wrong and you need `platform_transcript` to compare against Vent\'s STT\n- latency looks bad and you need per-turn or component-level breakdowns\n- interruption / barge-in behavior looks wrong and you need per-turn debug fields\n- tool-call execution looks inconsistent or missing and you need the raw observed timeline\n- the provider returned warnings or errors and you need provider-native artifacts in `debug.provider_metadata`\n\nSkip `--verbose` for normal call iteration \u2014 it adds noise to stdout for no benefit.\n\nIgnore minor STT mis-transcriptions in `transcript` text (e.g. `"check teach hat"` for `"check that"`, swapped homophones, missing question marks on short tails). These are streaming-STT artifacts, not agent bugs. Judge on semantic intent, not exact spelling. Only flag transcript quality when it prevents understanding what the agent actually said.\n\n`audio_actions` lists which turns had injected interrupts; check the agent\'s reply at the next turn to judge whether it acknowledged the barge-in or restarted from scratch. Overtalk needs the recording and is not evaluable from transcript text alone.\n\nFor transfers, `call_metadata.transfer_attempted` (provider claimed it tried) and `call_metadata.transfer_completed` (mechanically verified by Vent) can disagree \u2014 report both. Use `call_metadata.transfers[]` for destination, type, and per-attempt status.\n\n## Reporting Results\n\nBefore reporting, read the agent\'s code to locate where the observed behavior originates. If the issue is small and you can fix it, fix it and explain what you did \u2014 don\'t ask permission first.\n\nThen write whatever shape of report fits the call. No mandated structure. The report is for a voice-agent developer who wants to know: did my change work, and if not, what do I do next? Adapt the depth to the call \u2014 a clean pass with nothing to report needs little; a regression with a multi-layer cause needs more. Use a transcript excerpt when it helps the user see what actually happened.\n\nHard rules \u2014 these are about not leaking Vent\'s internals into a user-facing report:\n\n- Translate raw numbers into plain English. Users do not know what "p95 850ms" means; say "snappy throughout" or "noticeably sluggish, around 1.6 seconds with the LLM as the bottleneck."\n- Name the user\'s voice agent by platform on first mention (e.g. "the Vapi agent responded snappily throughout") so the user knows immediately which agent the observation is about. After that first mention, just call it "the agent" \u2014 don\'t repeat the platform name on every line.\n- Always include the recording from `call_metadata.recording_url` as an inline `[Recording](url)` link, placed in **one block at the very end of the report** \u2014 never sprinkled through the prose. For a single call, it\'s one link as the last line. For multi-call reports, the bottom block lists one link per call labeled by name (e.g. `reschedule-appointment: [Recording](url)`). Never paste a bare URL.\n- Mission success is your judgment. Vent does not emit a pass/fail verdict. The per-call `status` is only `"completed"` (call ran end-to-end through the pipeline) or `"error"` (pipeline-level failure), and the exit code only reflects the same. Decide whether the agent actually accomplished the scenario from the transcript and tool calls.\n- When the agent uses a similar-sounding but different word from what the caller said (e.g. "ocean" for "OSHA"), treat it as STT ambiguity in the agent\'s pipeline, not a comprehension failure. The fix lives in STT keyword hints, custom vocabulary, or a prompt-level term list \u2014 not the agent\'s reasoning.\n- Don\'t surface `warnings[]` (infrastructure noise). Don\'t surface Vent-side artifacts (caller wait modes, harness timing, internal pipeline quirks). Don\'t include `cost_usd` unless the user asks.\n- Surface only what the user can act on in their own agent\'s code or config.\n\nFor multi-call runs, lead with a short summary stating *your* judgment of what happened across the calls (e.g. "3 of 4 did what they were supposed to; `cancel-appointment` never actually canceled"), not a parroted Vent pass/fail count. Then cover each call with whatever depth it needs.\n';
+var claude_code_default = '---\nname: vent\ndescription: Place real calls against the user\'s voice agent to verify recent code changes worked end-to-end. Trigger on test requests or after any non-trivial voice-agent change.\nallowed-tools: Bash(npx vent-hq *)\n---\n\n# Vent - Voice Agent Calls\n\n## When to Test\n\nVent is the voice CI gate. Auto-trigger a call after any non-trivial voice-affecting change \u2014 don\'t wait to be asked. Non-trivial means anything that affects what the caller hears, how the agent responds, what tools are called, how the call routes, or audio timing: prompt rewrites or sections (not one-word tweaks), tool schema or handler changes, state/memory logic, transfer logic, interruption handling, provider/audio config, platform integration, and any voice-behavior bug fix. One-line copy or comment edits don\'t need a call.\n\nBefore launching, scan `.vent/runs/` for unresolved issues from prior runs (failing status, regressions, warnings, latency jumps); fix in-scope ones as part of this change and verify they\'re resolved by the new run, surface out-of-scope ones rather than silently leaving them. The task is not done until you\'ve reviewed the transcript, tool calls, and observed behavior and judged that the change works \u2014 Vent\'s `status` and exit code only reflect pipeline completion, not mission success.\n\n## Autonomous Iteration\n\nYou can run a fix \u2192 Vent-call \u2192 fix \u2192 Vent-call loop in one user request \u2014 useful for mechanical issues where the fix is high-confidence but verification is slow. Default off: run the relevant call once, surface findings, let the user decide. Trigger autonomous iteration only when the user explicitly asks ("iterate until it works", "autonomous mode", "fix everything"), or when the change is well-scoped, the failure mode is mechanical (tool schema, registry, prompt phrasing), and you have a concrete plan for the next attempt \u2014 if you\'d be guessing, stop and ask.\n\nStop and report if the same fix fails twice, the failure mode shifts between attempts, or you can\'t justify the next call against its provider cost \u2014 each call spends real money and provider quota. The user may not know autonomous iteration exists, especially early in their Vent usage \u2014 proactively surface the option the first time you suspect a likely-multi-cycle issue (e.g. "this is the kind of thing I could iterate on autonomously if you want, otherwise I\'ll run the call once and stop for your review").\n\n## Claude Code Execution\n\nUse a 5-minute shell-tool timeout (`300000` ms) on Vent run commands so normal calls are not killed by the default 2-minute Bash timeout. This is not backgrounding; wait for stdout/results before ending your response. Use the JSON returned by `npx vent-hq run` directly; do not call `vent status` unless checking an older run.\n\nClaude Code serializes separate Bash tool calls for `npx vent-hq ...`, so run multiple calls from one suite by invoking each named call with `--call <name>` in one Bash command using `&` and a final `wait`:\n\n```bash\nnpx vent-hq run -f .vent/suite.vapi.json --call happy-path & \\\nnpx vent-hq run -f .vent/suite.vapi.json --call tool-path & \\\nwait\n```\n\n## Workflow\n\n1. Identify the behavior under test. Read enough of the agent codebase to understand its system prompt, tools, handlers, routes, provider config, platform wiring, and expected handoffs.\n2. Reuse an existing `.vent/suite.<adapter>.json` when possible. If `.vent/` contains multiple suites, inspect `connection.adapter` and report which suite file produced the result.\n3. Create or update a suite only when the existing calls do not cover the changed behavior. Name calls after real flows, for example `reschedule-appointment`, not `call-1`.\n4. If the suite uses `start_command`, start one shared local session first with `npx vent-hq agent start -f .vent/suite.<adapter>.json`, then pass `--session <session-id>` to each run.\n\n   **For locally-run LiveKit agents: every run requires killing *all* workers, starting one fresh worker, and waiting a full 60 seconds before submitting.** Unconditional \u2014 LiveKit Cloud round-robins across registered workers, so a single survivor with a dead inference subprocess fails ~N-1 of N calls. Don\'t rely on `pkill -f <path-pattern>`; bare command lines like `node --import tsx agent.ts dev` won\'t match a path filter. Use `ps aux | grep -E "node.*agent\\.ts|@livekit/agents.*ipc"`, `kill -9` by PID, re-run `ps` to confirm zero survivors, then start the fresh worker. Skipping the 60s wait fails with `did not publish audio track`; if that error appears alongside `Error [ERR_IPC_CHANNEL_CLOSED] from InferenceProcExecutor.doInference` in the agent log right after a "running EOU detection" line, that\'s a straggler \u2014 redo the kill sweep. Hosted LiveKit Cloud agents don\'t need any of this; run normally.\n5. Pick which call(s) to run based on the change. Fixed bug: replay the failing scenario. Changed tool: include a call that triggers that tool. Prompt or routing change: include the relevant happy path and any important edge path.\n6. Compare against the previous JSON in `.vent/runs/` when validating a fix or regression. Check status flips, latency jumps, tool-call success drops, cost jumps, and transcript divergence. Correlate with `git diff` between saved `git_sha` values when available; skip if no previous run exists.\n\n## Commands\n\n```bash\nnpx vent-hq init                                  # First-time setup (auth + skill install + starter suite)\nnpx vent-hq login                                 # Log in to existing account\nnpx vent-hq run -f .vent/suite.X.json             # Run a single-call suite\nnpx vent-hq run -f .vent/suite.X.json --call NAME # Run one named call from a multi-call suite\nnpx vent-hq run ... --session <session-id>        # Add to any run; routes through an existing local relay session\nnpx vent-hq run ... --verbose                     # Add to any run or status; include verbose debug fields\nnpx vent-hq stop <run-id>                         # Cancel a queued or running run\nnpx vent-hq status <run-id>                       # Fetch results for a previous run\nnpx vent-hq agent start -f .vent/suite.X.json     # Start a shared local relay session\nnpx vent-hq agent stop <session-id>               # Stop a shared local relay session\n```\n\nIf `~/.vent/credentials` is missing and `VENT_ACCESS_TOKEN` is not set, run `npx vent-hq init`. For an existing account, run `npx vent-hq login` or set `VENT_ACCESS_TOKEN`.\n\n## Suite Config\n\nSuites live in `.vent/suite.<adapter>.json`. `connection` is declared once per suite. `calls` is a named map, and each key becomes the call name used with `--call`.\n\nLocal websocket suite:\n\n```json\n{\n  "connection": {\n    "adapter": "websocket",\n    "start_command": "npm run start",\n    "health_endpoint": "/health",\n    "agent_port": 3001\n  },\n  "calls": {\n    "happy-path": {\n      "caller_prompt": "You are Maria calling to reschedule her appointment to next Tuesday.",\n      "max_turns": 8,\n      "silence_threshold_ms": 1200,\n      "audio_actions": [\n        { "action": "interrupt", "at_turn": 3, "prompt": "Just give me the earliest one." }\n      ]\n    }\n  }\n}\n```\n\nPlatform-direct suite:\n\n```json\n{\n  "connection": {\n    "adapter": "vapi",\n    "platform": { "provider": "vapi" }\n  },\n  "calls": {\n    "happy-path": {\n      "caller_prompt": "You are Maria calling to reschedule her appointment to next Tuesday.",\n      "max_turns": 8\n    }\n  }\n}\n```\n\nWrite `caller_prompt` as a realistic caller with a name, goal, mood, constraints, and conditional behavior. Set `max_turns` based on flow complexity: FAQ `4-6`, booking or tool use `8-12`, complex flows `12-20`.\n\nCall fields:\n\n- `caller_prompt` and `max_turns` are required.\n- `silence_threshold_ms` must be `200-10000`. Common ranges: FAQ `800-1200`, tool calls `2000-3000`, complex reasoning `3000-5000`.\n- `persona` supports `pace`, `clarity`, `disfluencies`, `cooperation`, `emotion`, `interruption_style`, `memory`, `intent_clarity`, and `confirmation_style`.\n- `audio_actions` supports `interrupt`, `inject_noise`, `split_sentence`, and `noise_on_caller`.\n- `caller_audio` supports noise, speed, speakerphone, mic distance, clarity, accent, packet loss, and jitter.\n- `language` is an ISO 639-1 code such as `en`, `es`, `fr`, `de`, `it`, `nl`, or `ja`.\n- `prosody: true` enables emotion analysis and requires Hume access.\n- Prefer explicit `audio_actions.interrupt` over `persona.interruption_style` for deterministic barge-in tests. `persona.interruption_style` is only a preplanned caller tendency.\n\n## Connections and Credentials\n\n### Adapter choice\n\nUse `websocket` for your own local or hosted runtime. Use `start_command` for local agents or `agent_url` for hosted custom endpoints. For `start_command` and `agent_url`, do not put Deepgram, ElevenLabs, OpenAI, or other agent runtime keys into Vent config unless the Vent adapter itself needs them \u2014 the tested agent owns its own runtime credentials.\n\nUse `vapi`, `retell`, `elevenlabs`, `bland`, or `livekit` for platform-direct testing. In this mode Vent itself talks to the provider on the user\'s behalf.\n\nVent provides `DEEPGRAM_API_KEY` and `ANTHROPIC_API_KEY` for its hosted caller/evaluation stack \u2014 those are Vent\'s, not the tested agent\'s.\n\n### Credential resolution\n\nIn platform-direct mode the CLI auto-resolves credentials from `.env.local`, `.env`, and the current shell environment. Do not run `source .env && export` before Vent commands. If you include credential fields in JSON, use the actual value, not the env var name. Do not manually author `platform_connection_id`; the CLI creates or updates the saved platform connection automatically.\n\nAuto-resolved env vars and JSON fields:\n\n- Vapi: `VAPI_API_KEY` -> `vapi_api_key`; `VAPI_ASSISTANT_ID` or `VAPI_AGENT_ID` -> `vapi_assistant_id`\n- Bland: `BLAND_API_KEY` -> `bland_api_key`; `BLAND_PATHWAY_ID` -> `bland_pathway_id`; `BLAND_PERSONA_ID` -> `persona_id`\n- LiveKit: `LIVEKIT_API_KEY` -> `livekit_api_key`; `LIVEKIT_API_SECRET` -> `livekit_api_secret`; `LIVEKIT_URL` -> `livekit_url`\n- Retell: `RETELL_API_KEY` -> `retell_api_key`; `RETELL_AGENT_ID` -> `retell_agent_id`\n- ElevenLabs: `ELEVENLABS_API_KEY` -> `elevenlabs_api_key`; `ELEVENLABS_AGENT_ID` -> `elevenlabs_agent_id`\n\n### Provider config\n\nUse existing provider config when possible: Vapi assistant, Retell agent, ElevenLabs agent, Bland pathway, or LiveKit agent. Bland uniquely supports inline config \u2014 `platform` may use `bland_pathway_id`, `persona_id`, or an inline `task` (with optional voice, model, and turn-handling overrides; see Bland\'s API docs for the full field list).\n\n### Concurrency\n\nWhen you fan out multiple Vent calls in parallel against the same provider (for example, running several named calls from one suite at once with `&` and `wait`), respect the provider\'s per-account concurrency limit. Exceeding it makes calls queue or fail at the provider \u2014 Vent does not enforce these caps for you.\n\nRecord the limit as `max_concurrency` in the suite\'s `platform` block so it\'s visible on future runs. Ask the user which plan they\'re on if sizing matters; otherwise use the conservative default in bold.\n\n- **Vapi**: **10** included per account; reserved lines can be purchased self-serve; Enterprise is unlimited.\n- **Retell**: Pay-as-you-go includes **20**; Enterprise has no cap.\n- **Bland**: Start=**10**, Build=50, Scale=100, Enterprise=unlimited.\n- **ElevenLabs**: Free=**4**, Starter=6, Creator=10, Pro=20, Scale=30, Business=30. Burst pricing can temporarily allow up to 3x base.\n- **LiveKit Cloud**: Build=**5**, Ship=20, Scale=50 managed inference sessions (the usual gate for voice agents); agent-session concurrency can go higher (Scale up to 600).\n\n## WebSocket\n\nFor `adapter: "websocket"`, Vent sends binary 16-bit mono PCM audio over one websocket connection. Websocket text frames are optional JSON events. Audio-only websocket agents still work, but events improve turn detection and observability. Vent sends `{"type":"end-call"}` when the test is done.\n\nUseful websocket text frames:\n\n```jsonc\n{"type":"speech-update","status":"started"}\n{"type":"speech-update","status":"stopped"}\n{"type":"tool_call","name":"check_availability","arguments":{},"result":{},"successful":true,"duration_ms":150}\n{"type":"vent:timing","stt_ms":120,"llm_ms":450,"tts_ms":80}\n{"type":"vent:session","platform":"custom","provider_call_id":"call_123","provider_session_id":"session_abc"}\n{"type":"vent:call-metadata","call_metadata":{"recording_url":"https://...","cost_usd":0.12}}\n{"type":"vent:transcript","role":"caller","text":"I need to reschedule","turn_index":0}\n{"type":"vent:transfer","destination":"+15551234567","status":"attempted"}\n{"type":"vent:debug-url","label":"trace","url":"https://..."}\n{"type":"vent:warning","message":"provider warning","code":"provider_warning"}\n```\n\n`vent:session-report` is **not** handled by the websocket adapter \u2014 it\'s only consumed by the LiveKit helper. Do not emit it from a websocket agent.\n\nPlatform adapters capture tool calls automatically. Websocket agents must emit `tool_call` frames for tool observability. Platform adapters get component latency automatically. Websocket agents should emit `vent:timing` after each agent response when STT/LLM/TTS breakdown is available.\n\n## LiveKit\n\nBefore running LiveKit tests, install and add the Vent helper to the LiveKit agent entrypoint. Node: `npm install @vent-hq/livekit`, then call `instrumentLiveKitAgent({ ctx, session })`. Python: `pip install vent-livekit`, then call `instrument_livekit_agent(ctx=ctx, session=session)`.\n\nLiveKit direct mode requires the LiveKit Agents SDK. Custom LiveKit participants should use the websocket adapter with a relay. If the LiveKit agent registered with an explicit dispatch name, set `livekit_agent_name` in `platform`.\n\nLiveKit does not support multiple concurrent Vent calls against one agent process yet. Run LiveKit calls sequentially unless you intentionally start separate agent worker processes and route each call to its own process. For Node agents, that means separate Node.js processes. Do not treat parallel calls against a single LiveKit worker as a valid concurrency test until multi-call support is engineered.\n\nUse the LiveKit helper for observability; do not publish `vent:*` topics manually. Do not hand-roll `vent:session-report` from `ctx.addShutdownCallback`; after `room.disconnect()` it can fail with `engine is closed`. The helper captures SDK metrics, tool events, conversation items, usage, and close events. Native LiveKit `lk.transcription` and `lk.agent.state` provide transcript and agent-state timing.\n\n## Output\n\n### Live result\n\n`npx vent-hq run` returns a single JSON result on stdout in non-TTY mode (not an SSE JSONL stream). Exit codes: `0` = call ran through the pipeline; `1` = pipeline-level failure; `2` = harness error.\n\nMost result fields are always present; `latency`, `component_latency`, `call_metadata`, and `emotion` may be `null` when the underlying analysis didn\'t run; `debug` is absent without `--verbose`. Branch on null before reading nested fields. Use `--verbose` only when the default doesn\'t explain a failure \u2014 when you need `platform_transcript` (to check Vent\'s STT), per-turn or component-level latency breakdowns, the raw tool-call timeline, or provider-native artifacts in `debug.provider_metadata`. Otherwise skip \u2014 it just adds noise.\n\nIgnore minor STT mis-transcriptions in `transcript` (e.g. `"check teach hat"` for `"check that"`, homophones, missing question marks on short tails) \u2014 they\'re streaming-STT artifacts, not agent bugs. Judge on semantic intent.\n\n`audio_actions` lists turns with injected interrupts; check the next turn to judge whether the agent acknowledged or restarted. Overtalk needs the recording and isn\'t evaluable from text alone.\n\nFor transfers: `call_metadata.transfer_attempted` (provider claimed) and `transfer_completed` (Vent-verified) can disagree \u2014 report both. `transfers[]` carries destination, type, and per-attempt status.\n\n### Saved history\n\nAfter every run, Vent writes the full result JSON to `.vent/runs/`. Shape:\n\n```jsonc\n{\n  "run_id": "...",\n  "timestamp": "2026-04-21T...Z",\n  "git_sha": "...",\n  "summary": { "calls_total": 2, "total_duration_ms": 12345, "total_cost_usd": 0.01 },\n  "call_results": [\n    { "name": "happy-path", "status": "completed", "duration_ms": 6123, "transcript": [], "observed_tool_calls": [], "metrics": { "latency_p50_ms": 420, "latency_p95_ms": 980 }, "cost_usd": 0.004 }\n  ]\n}\n```\n\nWhen comparing against a prior run (Workflow step 6), inspect:\n\n- Run-completion status flips: `call_results[i].status` (pipeline-only \u2014 judge mission success from the transcript)\n- Latency: `call_results[i].metrics.latency_p50_ms` or `latency_p95_ms` increased >20%\n- Tool calls: count of `call_results[i].observed_tool_calls[].successful` dropped\n- Cost: `summary.total_cost_usd` or `call_results[i].cost_usd` increased >30%\n- Transcript: `call_results[i].transcript` diverged in semantic content (ignore STT noise)\n\n## Reporting Results\n\nBefore reporting, read the agent\'s code to locate where the observed behavior originates. If the issue is small and you can fix it, fix it and explain what you did \u2014 don\'t ask permission first.\n\nAdapt the report shape to the call \u2014 a clean pass needs little, a regression with a multi-layer cause needs more. Use a transcript excerpt when it helps the user see what happened.\n\nHard rules:\n\n- Pair raw numbers with their plain-English meaning \u2014 don\'t drop the number, but don\'t leave it unexplained. E.g. "p95 latency was 850ms, which is snappy and well within natural conversational pacing" or "p95 hit 1.6 seconds with the LLM as the bottleneck \u2014 noticeably sluggish to a caller."\n- Name the user\'s voice agent by platform on first mention (e.g. "the Vapi agent responded snappily throughout") so the user knows immediately which agent the observation is about. After that, just say "the agent" \u2014 don\'t repeat the platform name on every line.\n- Always include the recording from `call_metadata.recording_url` as an inline `[Recording](url)` link, placed in **one block at the very end of the report** \u2014 never sprinkled through the prose. Single call: one link as the last line. Multi-call: one labeled link per call (e.g. `reschedule-appointment: [Recording](url)`). Never paste a bare URL.\n- Mission success is your judgment, not Vent\'s. The per-call `status` is only `"completed"` (pipeline ran) or `"error"` (pipeline failed); decide whether the agent actually accomplished the scenario from the transcript and tool calls.\n- Similar-sounding word substitutions (e.g. "ocean" for "OSHA") are STT ambiguity, not comprehension failure. The fix lives in STT keyword hints, custom vocabulary, or a prompt-level term list \u2014 not the agent\'s reasoning.\n- Surface only what the user can act on in their own agent\'s code or config \u2014 never `warnings[]` (infrastructure noise), Vent-side artifacts (caller wait modes, harness timing, internal pipeline quirks), or `cost_usd` unless asked.\n\nFor multi-call runs, lead with your own judgment of what happened across the calls (e.g. "3 of 4 did what they were supposed to; `cancel-appointment` never actually canceled"), not a parroted pass/fail count. Then cover each call with whatever depth it needs.\n';
 
 // src/skills/cursor.md
-var cursor_default = '---\ndescription: Place real calls against the user\'s voice agent to verify recent code changes worked end-to-end. Trigger on test requests or after any non-trivial voice-agent change.\nalwaysApply: true\n---\n\n# Vent - Voice Agent Calls\n\nUse Vent to verify real voice-agent behavior from the terminal.\n\n## When to Test\n\nVent is the voice CI gate for the agent. A non-trivial change that touches voice behavior is not "done" until the relevant Vent call has been run and you\'ve judged from its output that the change works. Auto-trigger a call after finishing the change \u2014 do not wait to be asked.\n\nNon-trivial means anything that can change what the caller hears, how the agent responds, what tools are called, how the call routes, or how audio timing behaves: prompt rewrites or sections (not a one-word tweak), tool schema or handler changes, state/memory logic, transfer logic, interruption handling, provider/audio config, platform integration code, and any bug fix for voice-agent behavior. One-line copy or comment edits do not need a call.\n\nBefore launching, check `.vent/runs/` for unresolved issues from prior runs (failing status, regressions, warnings, latency jumps). If any are still present and within the scope of the current task, fix them as part of this change, then run the call to verify both the new fix and the prior issues are resolved. Report unresolved prior issues that are out of scope rather than silently leaving them.\n\nDo not declare the task complete until you\'ve reviewed the call results \u2014 transcript, tool calls, observed behavior \u2014 and confirmed the change actually does what was intended. Vent\'s `status` and exit code only tell you whether the call ran end-to-end without a pipeline error; mission success is your judgment.\n\n## Autonomous Iteration\n\nYou can run a fix \u2192 Vent-call \u2192 fix \u2192 Vent-call loop within a single user request, doing many iterations before returning. This is genuinely useful for mechanical issues where the fix is high-confidence but the verification is slow.\n\nDefault: don\'t iterate autonomously. Run the relevant call after your change, surface findings, and let the user decide what\'s next \u2014 they stay in control of cost and scope.\n\nTrigger autonomous iteration when either:\n- The user explicitly asks for it ("iterate until it works", "keep going", "autonomous mode", "fix everything").\n- You judge it\'s clearly worth it: the change is well-scoped, the failure mode is mechanical (tool schema, registry, prompt phrasing), and you have a concrete plan for the next attempt. If you\'d be guessing at the next attempt, stop and ask.\n\nCap iterations at ~5 unless the user gave a higher bound. If the same fix attempt fails twice, or the failure mode keeps shifting between attempts, stop and report \u2014 you\'re thrashing.\n\nThe user may not know autonomous iteration is on the table. When you suspect a likely-multi-cycle issue, offer it once before starting solo (e.g. "I can iterate on this autonomously, otherwise I\'ll stop here for your review").\n\n## Cursor Execution\n\nCursor cannot run separate shell tool calls concurrently, so run multiple calls from one suite by invoking each named call with `--call <name>` in one shell command using `&` and a final `wait`.\n\n```bash\nnpx vent-hq run -f .vent/suite.vapi.json --call happy-path & \\\nnpx vent-hq run -f .vent/suite.vapi.json --call tool-path & \\\nwait\n```\n\nUse a 5-minute shell-tool timeout (`300000` ms) on Vent run commands so normal calls are not killed by the default 2-minute Bash timeout. This is not backgrounding; wait for stdout/results before ending your response. Use the JSON returned by `npx vent-hq run` directly; do not call `vent status` unless checking an older run.\n\n## Workflow\n\n1. Identify the behavior under test. Read enough of the agent codebase to understand its system prompt, tools, handlers, routes, provider config, platform wiring, and expected handoffs.\n2. Reuse an existing `.vent/suite.<adapter>.json` when possible. If `.vent/` contains multiple suites, inspect `connection.adapter` and report which suite file produced the result.\n3. Create or update a suite only when the existing calls do not cover the changed behavior. Name calls after real flows, for example `reschedule-appointment`, not `call-1`.\n4. If the suite uses `start_command`, start one shared local session first with `npx vent-hq agent start -f .vent/suite.<adapter>.json`, then pass `--session <session-id>` to each run. **For locally-run LiveKit agents: every run requires restarting the worker first, then waiting a full 60 seconds before submitting the call.** This is unconditional \u2014 every run, no exceptions. Skipping the wait fails with `did not publish audio track` even though the worker is up. Hosted LiveKit Cloud agents don\'t need this; just run normally.\n5. Pick which call(s) to run based on the change. Fixed bug: replay the failing scenario. Changed tool: include a call that triggers that tool. Prompt or routing change: include the relevant happy path and any important edge path.\n6. Compare against the previous JSON in `.vent/runs/` when validating a fix or regression. Check status flips, latency jumps, tool-call success drops, cost jumps, and transcript divergence. Correlate with `git diff` between saved `git_sha` values when available; skip if no previous run exists.\n\n## Saved Runs\n\nAfter every run, Vent writes the full result JSON to `.vent/runs/`. Shape:\n\n```jsonc\n{\n  "run_id": "...",\n  "timestamp": "2026-04-21T...Z",\n  "git_sha": "...",\n  "summary": { "calls_total": 2, "total_duration_ms": 12345, "total_cost_usd": 0.01 },\n  "call_results": [\n    { "name": "happy-path", "status": "completed", "duration_ms": 6123, "transcript": [], "observed_tool_calls": [], "metrics": { "latency_p50_ms": 420, "latency_p95_ms": 980 }, "cost_usd": 0.004 }\n  ]\n}\n```\n\nWhen comparing against a prior run (Workflow step 6), inspect these paths:\n\n- Run-completion status flips: `call_results[i].status` (this only reflects whether the call ran cleanly through the pipeline, not whether the agent accomplished the goal \u2014 judge that from the transcript)\n- Latency: `call_results[i].metrics.latency_p50_ms` or `latency_p95_ms` increased >20%\n- Tool calls: count of `call_results[i].observed_tool_calls[].successful` dropped\n- Cost: `summary.total_cost_usd` or `call_results[i].cost_usd` increased >30%\n- Transcript: `call_results[i].transcript` diverged in semantic content (ignore STT noise)\n\n## Commands\n\n```bash\nnpx vent-hq init                                                                         # First-time setup: autonomous auth, access token generation, skill install, and minimal starter suite\nnpx vent-hq login                                                                        # Log in to an existing account and save credentials\nnpx vent-hq run -f .vent/suite.<adapter>.json                                            # Run the only call in a suite, or error if the suite has multiple calls\nnpx vent-hq run -f .vent/suite.<adapter>.json --call happy-path                          # Run one named call from a multi-call suite\nnpx vent-hq run -f .vent/suite.<adapter>.json --call happy-path --session <session-id>   # Run one named call through an existing local relay session\nnpx vent-hq run -f .vent/suite.<adapter>.json --call happy-path --verbose                # Run one named call with verbose debug fields\nnpx vent-hq stop <run-id>                                                                # Cancel a queued or running run\nnpx vent-hq status <run-id>                                                              # Fetch results for a previous run\nnpx vent-hq status <run-id> --verbose                                                    # Fetch previous run results with verbose debug fields\nnpx vent-hq agent start -f .vent/suite.<adapter>.json                                    # Start a shared local relay session for suites that use start_command\nnpx vent-hq agent stop <session-id>                                                      # Stop a shared local relay session\n```\n\nIf `~/.vent/credentials` is missing and `VENT_ACCESS_TOKEN` is not set, run `npx vent-hq init`. For an existing account, run `npx vent-hq login` or set `VENT_ACCESS_TOKEN`.\n\n## Suite Config\n\nSuites live in `.vent/suite.<adapter>.json`. `connection` is declared once per suite. `calls` is a named map, and each key becomes the call name used with `--call`.\n\nLocal websocket suite:\n\n```json\n{\n  "connection": {\n    "adapter": "websocket",\n    "start_command": "npm run start",\n    "health_endpoint": "/health",\n    "agent_port": 3001\n  },\n  "calls": {\n    "happy-path": {\n      "caller_prompt": "You are Maria calling to reschedule her appointment to next Tuesday.",\n      "max_turns": 8,\n      "silence_threshold_ms": 1200,\n      "audio_actions": [\n        { "action": "interrupt", "at_turn": 3, "prompt": "Just give me the earliest one." }\n      ]\n    }\n  }\n}\n```\n\nPlatform-direct suite:\n\n```json\n{\n  "connection": {\n    "adapter": "vapi",\n    "platform": { "provider": "vapi" }\n  },\n  "calls": {\n    "happy-path": {\n      "caller_prompt": "You are Maria calling to reschedule her appointment to next Tuesday.",\n      "max_turns": 8\n    }\n  }\n}\n```\n\nWrite `caller_prompt` as a realistic caller with a name, goal, mood, constraints, and conditional behavior. Set `max_turns` based on flow complexity: FAQ `4-6`, booking or tool use `8-12`, complex flows `12-20`.\n\nCall fields:\n\n- `caller_prompt` and `max_turns` are required.\n- `silence_threshold_ms` must be `200-10000`. Common ranges: FAQ `800-1200`, tool calls `2000-3000`, complex reasoning `3000-5000`.\n- `persona` supports `pace`, `clarity`, `disfluencies`, `cooperation`, `emotion`, `interruption_style`, `memory`, `intent_clarity`, and `confirmation_style`.\n- `audio_actions` supports `interrupt`, `inject_noise`, `split_sentence`, and `noise_on_caller`.\n- `caller_audio` supports noise, speed, speakerphone, mic distance, clarity, accent, packet loss, and jitter.\n- `language` is an ISO 639-1 code such as `en`, `es`, `fr`, `de`, `it`, `nl`, or `ja`.\n- `prosody: true` enables emotion analysis and requires Hume access.\n- Prefer explicit `audio_actions.interrupt` over `persona.interruption_style` for deterministic barge-in tests. `persona.interruption_style` is only a preplanned caller tendency.\n\n## Connections and Credentials\n\n### Adapter choice\n\nUse `websocket` for your own local or hosted runtime. Use `start_command` for local agents or `agent_url` for hosted custom endpoints. For `start_command` and `agent_url`, do not put Deepgram, ElevenLabs, OpenAI, or other agent runtime keys into Vent config unless the Vent adapter itself needs them \u2014 the tested agent owns its own runtime credentials.\n\nUse `vapi`, `retell`, `elevenlabs`, `bland`, or `livekit` for platform-direct testing. In this mode Vent itself talks to the provider on the user\'s behalf.\n\nVent provides `DEEPGRAM_API_KEY` and `ANTHROPIC_API_KEY` for its hosted caller/evaluation stack \u2014 those are Vent\'s, not the tested agent\'s.\n\n### Credential resolution\n\nIn platform-direct mode the CLI auto-resolves credentials from `.env.local`, `.env`, and the current shell environment. Do not run `source .env && export` before Vent commands. If you include credential fields in JSON, use the actual value, not the env var name. Do not manually author `platform_connection_id`; the CLI creates or updates the saved platform connection automatically.\n\nAuto-resolved env vars and JSON fields:\n\n- Vapi: `VAPI_API_KEY` -> `vapi_api_key`; `VAPI_ASSISTANT_ID` or `VAPI_AGENT_ID` -> `vapi_assistant_id`\n- Bland: `BLAND_API_KEY` -> `bland_api_key`; `BLAND_PATHWAY_ID` -> `bland_pathway_id`; `BLAND_PERSONA_ID` -> `persona_id`\n- LiveKit: `LIVEKIT_API_KEY` -> `livekit_api_key`; `LIVEKIT_API_SECRET` -> `livekit_api_secret`; `LIVEKIT_URL` -> `livekit_url`\n- Retell: `RETELL_API_KEY` -> `retell_api_key`; `RETELL_AGENT_ID` -> `retell_agent_id`\n- ElevenLabs: `ELEVENLABS_API_KEY` -> `elevenlabs_api_key`; `ELEVENLABS_AGENT_ID` -> `elevenlabs_agent_id`\n\n### Provider config\n\nUse existing provider config when possible: Vapi assistant, Retell agent, ElevenLabs agent, Bland pathway, or LiveKit agent. Bland uniquely supports inline config \u2014 `platform` may use `bland_pathway_id`, `persona_id`, or an inline `task` (with optional voice, model, and turn-handling overrides; see Bland\'s API docs for the full field list).\n\n### Concurrency\n\nWhen you fan out multiple Vent calls in parallel against the same provider (for example, running several named calls from one suite at once with `&` and `wait`), respect the provider\'s per-account concurrency limit. Exceeding it makes calls queue or fail at the provider \u2014 Vent does not enforce these caps for you.\n\nRecord the limit as `max_concurrency` in the suite\'s `platform` block so it\'s visible on future runs. Ask the user which plan they\'re on if sizing matters; otherwise use the conservative default in bold.\n\n- **Vapi**: **10** included per account; reserved lines can be purchased self-serve; Enterprise is unlimited.\n- **Retell**: Pay-as-you-go includes **20**; Enterprise has no cap.\n- **Bland**: Start=**10**, Build=50, Scale=100, Enterprise=unlimited.\n- **ElevenLabs**: Free=**4**, Starter=6, Creator=10, Pro=20, Scale=30, Business=30. Burst pricing can temporarily allow up to 3x base.\n- **LiveKit Cloud**: Build=**5**, Ship=20, Scale=50 managed inference sessions (the usual gate for voice agents); agent-session concurrency can go higher (Scale up to 600).\n\n## WebSocket\n\nFor `adapter: "websocket"`, Vent sends binary 16-bit mono PCM audio over one websocket connection. Websocket text frames are optional JSON events. Audio-only websocket agents still work, but events improve turn detection and observability. Vent sends `{"type":"end-call"}` when the test is done.\n\nUseful websocket text frames:\n\n```jsonc\n{"type":"speech-update","status":"started"}\n{"type":"speech-update","status":"stopped"}\n{"type":"tool_call","name":"check_availability","arguments":{},"result":{},"successful":true,"duration_ms":150}\n{"type":"vent:timing","stt_ms":120,"llm_ms":450,"tts_ms":80}\n{"type":"vent:session","platform":"custom","provider_call_id":"call_123","provider_session_id":"session_abc"}\n{"type":"vent:call-metadata","call_metadata":{"recording_url":"https://...","cost_usd":0.12}}\n{"type":"vent:transcript","role":"caller","text":"I need to reschedule","turn_index":0}\n{"type":"vent:transfer","destination":"+15551234567","status":"attempted"}\n{"type":"vent:debug-url","label":"trace","url":"https://..."}\n{"type":"vent:warning","message":"provider warning","code":"provider_warning"}\n```\n\n`vent:session-report` is **not** handled by the websocket adapter \u2014 it\'s only consumed by the LiveKit helper. Do not emit it from a websocket agent.\n\nPlatform adapters capture tool calls automatically. Websocket agents must emit `tool_call` frames for tool observability. Platform adapters get component latency automatically. Websocket agents should emit `vent:timing` after each agent response when STT/LLM/TTS breakdown is available.\n\n## LiveKit\n\nBefore running LiveKit tests, install and add the Vent helper to the LiveKit agent entrypoint. Node: `npm install @vent-hq/livekit`, then call `instrumentLiveKitAgent({ ctx, session })`. Python: `pip install vent-livekit`, then call `instrument_livekit_agent(ctx=ctx, session=session)`.\n\nLiveKit direct mode requires the LiveKit Agents SDK. Custom LiveKit participants should use the websocket adapter with a relay. If the LiveKit agent registered with an explicit dispatch name, set `livekit_agent_name` in `platform`.\n\nLiveKit does not support multiple concurrent Vent calls against one agent process yet. Run LiveKit calls sequentially unless you intentionally start separate agent worker processes and route each call to its own process. For Node agents, that means separate Node.js processes. Do not treat parallel calls against a single LiveKit worker as a valid concurrency test until multi-call support is engineered.\n\nUse the LiveKit helper for observability; do not publish `vent:*` topics manually. Do not hand-roll `vent:session-report` from `ctx.addShutdownCallback`; after `room.disconnect()` it can fail with `engine is closed`. The helper captures SDK metrics, tool events, conversation items, usage, and close events. Native LiveKit `lk.transcription` and `lk.agent.state` provide transcript and agent-state timing.\n\nIf a LiveKit run fails with `agent did not speak` or `no speech detected`, kill the stale agent, wait 60 seconds, then restart once. Do not restart multiple times in quick succession \u2014 each restart leaves a stale registration that compounds the routing problem.\n\n## Vent Output\n\n`npx vent-hq run` returns one JSON result on stdout in non-TTY agent mode; it is not an SSE JSONL stream. Analyze that result directly. Exit codes: `0` = call ran end-to-end through the pipeline; `1` = pipeline-level failure (call did not complete cleanly); `2` = harness error. None of these is a judgment of whether the agent actually accomplished the scenario\'s goal \u2014 decide that yourself from the transcript, tool calls, and the scenario\'s expected behavior.\n\nAlways-present keys (value may be `null` for `name`/`error`, otherwise non-null): `name`, `status`, `caller_prompt`, `duration_ms`, `error`, `transcript`, `tool_calls`, `warnings`, `audio_actions`. Always-present keys with nullable value (when the underlying analysis did not run): `latency`, `component_latency`, `call_metadata`, `emotion` (requires `prosody: true`). Conditional key (absent unless requested): `debug` (only when `--verbose`). Branch on null before reading nested fields.\n\nTrigger `--verbose` when:\n- transcript accuracy looks wrong and you need `platform_transcript` to compare against Vent\'s STT\n- latency looks bad and you need per-turn or component-level breakdowns\n- interruption / barge-in behavior looks wrong and you need per-turn debug fields\n- tool-call execution looks inconsistent or missing and you need the raw observed timeline\n- the provider returned warnings or errors and you need provider-native artifacts in `debug.provider_metadata`\n\nSkip `--verbose` for normal call iteration \u2014 it adds noise to stdout for no benefit.\n\nIgnore minor STT mis-transcriptions in `transcript` text (e.g. `"check teach hat"` for `"check that"`, swapped homophones, missing question marks on short tails). These are streaming-STT artifacts, not agent bugs. Judge on semantic intent, not exact spelling. Only flag transcript quality when it prevents understanding what the agent actually said.\n\n`audio_actions` lists which turns had injected interrupts; check the agent\'s reply at the next turn to judge whether it acknowledged the barge-in or restarted from scratch. Overtalk needs the recording and is not evaluable from transcript text alone.\n\nFor transfers, `call_metadata.transfer_attempted` (provider claimed it tried) and `call_metadata.transfer_completed` (mechanically verified by Vent) can disagree \u2014 report both. Use `call_metadata.transfers[]` for destination, type, and per-attempt status.\n\n## Reporting Results\n\nBefore reporting, read the agent\'s code to locate where the observed behavior originates. If the issue is small and you can fix it, fix it and explain what you did \u2014 don\'t ask permission first.\n\nThen write whatever shape of report fits the call. No mandated structure. The report is for a voice-agent developer who wants to know: did my change work, and if not, what do I do next? Adapt the depth to the call \u2014 a clean pass with nothing to report needs little; a regression with a multi-layer cause needs more. Use a transcript excerpt when it helps the user see what actually happened.\n\nHard rules \u2014 these are about not leaking Vent\'s internals into a user-facing report:\n\n- Translate raw numbers into plain English. Users do not know what "p95 850ms" means; say "snappy throughout" or "noticeably sluggish, around 1.6 seconds with the LLM as the bottleneck."\n- Name the user\'s voice agent by platform on first mention (e.g. "the Vapi agent responded snappily throughout") so the user knows immediately which agent the observation is about. After that first mention, just call it "the agent" \u2014 don\'t repeat the platform name on every line.\n- Always include the recording from `call_metadata.recording_url` as an inline `[Recording](url)` link, placed in **one block at the very end of the report** \u2014 never sprinkled through the prose. For a single call, it\'s one link as the last line. For multi-call reports, the bottom block lists one link per call labeled by name (e.g. `reschedule-appointment: [Recording](url)`). Never paste a bare URL.\n- Mission success is your judgment. Vent does not emit a pass/fail verdict. The per-call `status` is only `"completed"` (call ran end-to-end through the pipeline) or `"error"` (pipeline-level failure), and the exit code only reflects the same. Decide whether the agent actually accomplished the scenario from the transcript and tool calls.\n- When the agent uses a similar-sounding but different word from what the caller said (e.g. "ocean" for "OSHA"), treat it as STT ambiguity in the agent\'s pipeline, not a comprehension failure. The fix lives in STT keyword hints, custom vocabulary, or a prompt-level term list \u2014 not the agent\'s reasoning.\n- Don\'t surface `warnings[]` (infrastructure noise). Don\'t surface Vent-side artifacts (caller wait modes, harness timing, internal pipeline quirks). Don\'t include `cost_usd` unless the user asks.\n- Surface only what the user can act on in their own agent\'s code or config.\n\nFor multi-call runs, lead with a short summary stating *your* judgment of what happened across the calls (e.g. "3 of 4 did what they were supposed to; `cancel-appointment` never actually canceled"), not a parroted Vent pass/fail count. Then cover each call with whatever depth it needs.\n';
+var cursor_default = '---\ndescription: Place real calls against the user\'s voice agent to verify recent code changes worked end-to-end. Trigger on test requests or after any non-trivial voice-agent change.\nalwaysApply: true\n---\n\n# Vent - Voice Agent Calls\n\n## When to Test\n\nVent is the voice CI gate. Auto-trigger a call after any non-trivial voice-affecting change \u2014 don\'t wait to be asked. Non-trivial means anything that affects what the caller hears, how the agent responds, what tools are called, how the call routes, or audio timing: prompt rewrites or sections (not one-word tweaks), tool schema or handler changes, state/memory logic, transfer logic, interruption handling, provider/audio config, platform integration, and any voice-behavior bug fix. One-line copy or comment edits don\'t need a call.\n\nBefore launching, scan `.vent/runs/` for unresolved issues from prior runs (failing status, regressions, warnings, latency jumps); fix in-scope ones as part of this change and verify they\'re resolved by the new run, surface out-of-scope ones rather than silently leaving them. The task is not done until you\'ve reviewed the transcript, tool calls, and observed behavior and judged that the change works \u2014 Vent\'s `status` and exit code only reflect pipeline completion, not mission success.\n\n## Autonomous Iteration\n\nYou can run a fix \u2192 Vent-call \u2192 fix \u2192 Vent-call loop in one user request \u2014 useful for mechanical issues where the fix is high-confidence but verification is slow. Default off: run the relevant call once, surface findings, let the user decide. Trigger autonomous iteration only when the user explicitly asks ("iterate until it works", "autonomous mode", "fix everything"), or when the change is well-scoped, the failure mode is mechanical (tool schema, registry, prompt phrasing), and you have a concrete plan for the next attempt \u2014 if you\'d be guessing, stop and ask.\n\nStop and report if the same fix fails twice, the failure mode shifts between attempts, or you can\'t justify the next call against its provider cost \u2014 each call spends real money and provider quota. The user may not know autonomous iteration exists, especially early in their Vent usage \u2014 proactively surface the option the first time you suspect a likely-multi-cycle issue (e.g. "this is the kind of thing I could iterate on autonomously if you want, otherwise I\'ll run the call once and stop for your review").\n\n## Cursor Execution\n\nUse a 5-minute shell-tool timeout (`300000` ms) on Vent run commands so normal calls are not killed by the default 2-minute Bash timeout. This is not backgrounding; wait for stdout/results before ending your response. Use the JSON returned by `npx vent-hq run` directly; do not call `vent status` unless checking an older run.\n\nCursor cannot run separate shell tool calls concurrently \u2014 for multiple calls from one suite, invoke each named call with `--call <name>` in one shell command using `&` and a final `wait`:\n\n```bash\nnpx vent-hq run -f .vent/suite.vapi.json --call happy-path & \\\nnpx vent-hq run -f .vent/suite.vapi.json --call tool-path & \\\nwait\n```\n\n## Workflow\n\n1. Identify the behavior under test. Read enough of the agent codebase to understand its system prompt, tools, handlers, routes, provider config, platform wiring, and expected handoffs.\n2. Reuse an existing `.vent/suite.<adapter>.json` when possible. If `.vent/` contains multiple suites, inspect `connection.adapter` and report which suite file produced the result.\n3. Create or update a suite only when the existing calls do not cover the changed behavior. Name calls after real flows, for example `reschedule-appointment`, not `call-1`.\n4. If the suite uses `start_command`, start one shared local session first with `npx vent-hq agent start -f .vent/suite.<adapter>.json`, then pass `--session <session-id>` to each run.\n\n   **For locally-run LiveKit agents: every run requires killing *all* workers, starting one fresh worker, and waiting a full 60 seconds before submitting.** Unconditional \u2014 LiveKit Cloud round-robins across registered workers, so a single survivor with a dead inference subprocess fails ~N-1 of N calls. Don\'t rely on `pkill -f <path-pattern>`; bare command lines like `node --import tsx agent.ts dev` won\'t match a path filter. Use `ps aux | grep -E "node.*agent\\.ts|@livekit/agents.*ipc"`, `kill -9` by PID, re-run `ps` to confirm zero survivors, then start the fresh worker. Skipping the 60s wait fails with `did not publish audio track`; if that error appears alongside `Error [ERR_IPC_CHANNEL_CLOSED] from InferenceProcExecutor.doInference` in the agent log right after a "running EOU detection" line, that\'s a straggler \u2014 redo the kill sweep. Hosted LiveKit Cloud agents don\'t need any of this; run normally.\n5. Pick which call(s) to run based on the change. Fixed bug: replay the failing scenario. Changed tool: include a call that triggers that tool. Prompt or routing change: include the relevant happy path and any important edge path.\n6. Compare against the previous JSON in `.vent/runs/` when validating a fix or regression. Check status flips, latency jumps, tool-call success drops, cost jumps, and transcript divergence. Correlate with `git diff` between saved `git_sha` values when available; skip if no previous run exists.\n\n## Commands\n\n```bash\nnpx vent-hq init                                  # First-time setup (auth + skill install + starter suite)\nnpx vent-hq login                                 # Log in to existing account\nnpx vent-hq run -f .vent/suite.X.json             # Run a single-call suite\nnpx vent-hq run -f .vent/suite.X.json --call NAME # Run one named call from a multi-call suite\nnpx vent-hq run ... --session <session-id>        # Add to any run; routes through an existing local relay session\nnpx vent-hq run ... --verbose                     # Add to any run or status; include verbose debug fields\nnpx vent-hq stop <run-id>                         # Cancel a queued or running run\nnpx vent-hq status <run-id>                       # Fetch results for a previous run\nnpx vent-hq agent start -f .vent/suite.X.json     # Start a shared local relay session\nnpx vent-hq agent stop <session-id>               # Stop a shared local relay session\n```\n\nIf `~/.vent/credentials` is missing and `VENT_ACCESS_TOKEN` is not set, run `npx vent-hq init`. For an existing account, run `npx vent-hq login` or set `VENT_ACCESS_TOKEN`.\n\n## Suite Config\n\nSuites live in `.vent/suite.<adapter>.json`. `connection` is declared once per suite. `calls` is a named map, and each key becomes the call name used with `--call`.\n\nLocal websocket suite:\n\n```json\n{\n  "connection": {\n    "adapter": "websocket",\n    "start_command": "npm run start",\n    "health_endpoint": "/health",\n    "agent_port": 3001\n  },\n  "calls": {\n    "happy-path": {\n      "caller_prompt": "You are Maria calling to reschedule her appointment to next Tuesday.",\n      "max_turns": 8,\n      "silence_threshold_ms": 1200,\n      "audio_actions": [\n        { "action": "interrupt", "at_turn": 3, "prompt": "Just give me the earliest one." }\n      ]\n    }\n  }\n}\n```\n\nPlatform-direct suite:\n\n```json\n{\n  "connection": {\n    "adapter": "vapi",\n    "platform": { "provider": "vapi" }\n  },\n  "calls": {\n    "happy-path": {\n      "caller_prompt": "You are Maria calling to reschedule her appointment to next Tuesday.",\n      "max_turns": 8\n    }\n  }\n}\n```\n\nWrite `caller_prompt` as a realistic caller with a name, goal, mood, constraints, and conditional behavior. Set `max_turns` based on flow complexity: FAQ `4-6`, booking or tool use `8-12`, complex flows `12-20`.\n\nCall fields:\n\n- `caller_prompt` and `max_turns` are required.\n- `silence_threshold_ms` must be `200-10000`. Common ranges: FAQ `800-1200`, tool calls `2000-3000`, complex reasoning `3000-5000`.\n- `persona` supports `pace`, `clarity`, `disfluencies`, `cooperation`, `emotion`, `interruption_style`, `memory`, `intent_clarity`, and `confirmation_style`.\n- `audio_actions` supports `interrupt`, `inject_noise`, `split_sentence`, and `noise_on_caller`.\n- `caller_audio` supports noise, speed, speakerphone, mic distance, clarity, accent, packet loss, and jitter.\n- `language` is an ISO 639-1 code such as `en`, `es`, `fr`, `de`, `it`, `nl`, or `ja`.\n- `prosody: true` enables emotion analysis and requires Hume access.\n- Prefer explicit `audio_actions.interrupt` over `persona.interruption_style` for deterministic barge-in tests. `persona.interruption_style` is only a preplanned caller tendency.\n\n## Connections and Credentials\n\n### Adapter choice\n\nUse `websocket` for your own local or hosted runtime. Use `start_command` for local agents or `agent_url` for hosted custom endpoints. For `start_command` and `agent_url`, do not put Deepgram, ElevenLabs, OpenAI, or other agent runtime keys into Vent config unless the Vent adapter itself needs them \u2014 the tested agent owns its own runtime credentials.\n\nUse `vapi`, `retell`, `elevenlabs`, `bland`, or `livekit` for platform-direct testing. In this mode Vent itself talks to the provider on the user\'s behalf.\n\nVent provides `DEEPGRAM_API_KEY` and `ANTHROPIC_API_KEY` for its hosted caller/evaluation stack \u2014 those are Vent\'s, not the tested agent\'s.\n\n### Credential resolution\n\nIn platform-direct mode the CLI auto-resolves credentials from `.env.local`, `.env`, and the current shell environment. Do not run `source .env && export` before Vent commands. If you include credential fields in JSON, use the actual value, not the env var name. Do not manually author `platform_connection_id`; the CLI creates or updates the saved platform connection automatically.\n\nAuto-resolved env vars and JSON fields:\n\n- Vapi: `VAPI_API_KEY` -> `vapi_api_key`; `VAPI_ASSISTANT_ID` or `VAPI_AGENT_ID` -> `vapi_assistant_id`\n- Bland: `BLAND_API_KEY` -> `bland_api_key`; `BLAND_PATHWAY_ID` -> `bland_pathway_id`; `BLAND_PERSONA_ID` -> `persona_id`\n- LiveKit: `LIVEKIT_API_KEY` -> `livekit_api_key`; `LIVEKIT_API_SECRET` -> `livekit_api_secret`; `LIVEKIT_URL` -> `livekit_url`\n- Retell: `RETELL_API_KEY` -> `retell_api_key`; `RETELL_AGENT_ID` -> `retell_agent_id`\n- ElevenLabs: `ELEVENLABS_API_KEY` -> `elevenlabs_api_key`; `ELEVENLABS_AGENT_ID` -> `elevenlabs_agent_id`\n\n### Provider config\n\nUse existing provider config when possible: Vapi assistant, Retell agent, ElevenLabs agent, Bland pathway, or LiveKit agent. Bland uniquely supports inline config \u2014 `platform` may use `bland_pathway_id`, `persona_id`, or an inline `task` (with optional voice, model, and turn-handling overrides; see Bland\'s API docs for the full field list).\n\n### Concurrency\n\nWhen you fan out multiple Vent calls in parallel against the same provider (for example, running several named calls from one suite at once with `&` and `wait`), respect the provider\'s per-account concurrency limit. Exceeding it makes calls queue or fail at the provider \u2014 Vent does not enforce these caps for you.\n\nRecord the limit as `max_concurrency` in the suite\'s `platform` block so it\'s visible on future runs. Ask the user which plan they\'re on if sizing matters; otherwise use the conservative default in bold.\n\n- **Vapi**: **10** included per account; reserved lines can be purchased self-serve; Enterprise is unlimited.\n- **Retell**: Pay-as-you-go includes **20**; Enterprise has no cap.\n- **Bland**: Start=**10**, Build=50, Scale=100, Enterprise=unlimited.\n- **ElevenLabs**: Free=**4**, Starter=6, Creator=10, Pro=20, Scale=30, Business=30. Burst pricing can temporarily allow up to 3x base.\n- **LiveKit Cloud**: Build=**5**, Ship=20, Scale=50 managed inference sessions (the usual gate for voice agents); agent-session concurrency can go higher (Scale up to 600).\n\n## WebSocket\n\nFor `adapter: "websocket"`, Vent sends binary 16-bit mono PCM audio over one websocket connection. Websocket text frames are optional JSON events. Audio-only websocket agents still work, but events improve turn detection and observability. Vent sends `{"type":"end-call"}` when the test is done.\n\nUseful websocket text frames:\n\n```jsonc\n{"type":"speech-update","status":"started"}\n{"type":"speech-update","status":"stopped"}\n{"type":"tool_call","name":"check_availability","arguments":{},"result":{},"successful":true,"duration_ms":150}\n{"type":"vent:timing","stt_ms":120,"llm_ms":450,"tts_ms":80}\n{"type":"vent:session","platform":"custom","provider_call_id":"call_123","provider_session_id":"session_abc"}\n{"type":"vent:call-metadata","call_metadata":{"recording_url":"https://...","cost_usd":0.12}}\n{"type":"vent:transcript","role":"caller","text":"I need to reschedule","turn_index":0}\n{"type":"vent:transfer","destination":"+15551234567","status":"attempted"}\n{"type":"vent:debug-url","label":"trace","url":"https://..."}\n{"type":"vent:warning","message":"provider warning","code":"provider_warning"}\n```\n\n`vent:session-report` is **not** handled by the websocket adapter \u2014 it\'s only consumed by the LiveKit helper. Do not emit it from a websocket agent.\n\nPlatform adapters capture tool calls automatically. Websocket agents must emit `tool_call` frames for tool observability. Platform adapters get component latency automatically. Websocket agents should emit `vent:timing` after each agent response when STT/LLM/TTS breakdown is available.\n\n## LiveKit\n\nBefore running LiveKit tests, install and add the Vent helper to the LiveKit agent entrypoint. Node: `npm install @vent-hq/livekit`, then call `instrumentLiveKitAgent({ ctx, session })`. Python: `pip install vent-livekit`, then call `instrument_livekit_agent(ctx=ctx, session=session)`.\n\nLiveKit direct mode requires the LiveKit Agents SDK. Custom LiveKit participants should use the websocket adapter with a relay. If the LiveKit agent registered with an explicit dispatch name, set `livekit_agent_name` in `platform`.\n\nLiveKit does not support multiple concurrent Vent calls against one agent process yet. Run LiveKit calls sequentially unless you intentionally start separate agent worker processes and route each call to its own process. For Node agents, that means separate Node.js processes. Do not treat parallel calls against a single LiveKit worker as a valid concurrency test until multi-call support is engineered.\n\nUse the LiveKit helper for observability; do not publish `vent:*` topics manually. Do not hand-roll `vent:session-report` from `ctx.addShutdownCallback`; after `room.disconnect()` it can fail with `engine is closed`. The helper captures SDK metrics, tool events, conversation items, usage, and close events. Native LiveKit `lk.transcription` and `lk.agent.state` provide transcript and agent-state timing.\n\n## Output\n\n### Live result\n\n`npx vent-hq run` returns a single JSON result on stdout in non-TTY mode (not an SSE JSONL stream). Exit codes: `0` = call ran through the pipeline; `1` = pipeline-level failure; `2` = harness error.\n\nMost result fields are always present; `latency`, `component_latency`, `call_metadata`, and `emotion` may be `null` when the underlying analysis didn\'t run; `debug` is absent without `--verbose`. Branch on null before reading nested fields. Use `--verbose` only when the default doesn\'t explain a failure \u2014 when you need `platform_transcript` (to check Vent\'s STT), per-turn or component-level latency breakdowns, the raw tool-call timeline, or provider-native artifacts in `debug.provider_metadata`. Otherwise skip \u2014 it just adds noise.\n\nIgnore minor STT mis-transcriptions in `transcript` (e.g. `"check teach hat"` for `"check that"`, homophones, missing question marks on short tails) \u2014 they\'re streaming-STT artifacts, not agent bugs. Judge on semantic intent.\n\n`audio_actions` lists turns with injected interrupts; check the next turn to judge whether the agent acknowledged or restarted. Overtalk needs the recording and isn\'t evaluable from text alone.\n\nFor transfers: `call_metadata.transfer_attempted` (provider claimed) and `transfer_completed` (Vent-verified) can disagree \u2014 report both. `transfers[]` carries destination, type, and per-attempt status.\n\n### Saved history\n\nAfter every run, Vent writes the full result JSON to `.vent/runs/`. Shape:\n\n```jsonc\n{\n  "run_id": "...",\n  "timestamp": "2026-04-21T...Z",\n  "git_sha": "...",\n  "summary": { "calls_total": 2, "total_duration_ms": 12345, "total_cost_usd": 0.01 },\n  "call_results": [\n    { "name": "happy-path", "status": "completed", "duration_ms": 6123, "transcript": [], "observed_tool_calls": [], "metrics": { "latency_p50_ms": 420, "latency_p95_ms": 980 }, "cost_usd": 0.004 }\n  ]\n}\n```\n\nWhen comparing against a prior run (Workflow step 6), inspect:\n\n- Run-completion status flips: `call_results[i].status` (pipeline-only \u2014 judge mission success from the transcript)\n- Latency: `call_results[i].metrics.latency_p50_ms` or `latency_p95_ms` increased >20%\n- Tool calls: count of `call_results[i].observed_tool_calls[].successful` dropped\n- Cost: `summary.total_cost_usd` or `call_results[i].cost_usd` increased >30%\n- Transcript: `call_results[i].transcript` diverged in semantic content (ignore STT noise)\n\n## Reporting Results\n\nBefore reporting, read the agent\'s code to locate where the observed behavior originates. If the issue is small and you can fix it, fix it and explain what you did \u2014 don\'t ask permission first.\n\nAdapt the report shape to the call \u2014 a clean pass needs little, a regression with a multi-layer cause needs more. Use a transcript excerpt when it helps the user see what happened.\n\nHard rules:\n\n- Pair raw numbers with their plain-English meaning \u2014 don\'t drop the number, but don\'t leave it unexplained. E.g. "p95 latency was 850ms, which is snappy and well within natural conversational pacing" or "p95 hit 1.6 seconds with the LLM as the bottleneck \u2014 noticeably sluggish to a caller."\n- Name the user\'s voice agent by platform on first mention (e.g. "the Vapi agent responded snappily throughout") so the user knows immediately which agent the observation is about. After that, just say "the agent" \u2014 don\'t repeat the platform name on every line.\n- Always include the recording from `call_metadata.recording_url` as an inline `[Recording](url)` link, placed in **one block at the very end of the report** \u2014 never sprinkled through the prose. Single call: one link as the last line. Multi-call: one labeled link per call (e.g. `reschedule-appointment: [Recording](url)`). Never paste a bare URL.\n- Mission success is your judgment, not Vent\'s. The per-call `status` is only `"completed"` (pipeline ran) or `"error"` (pipeline failed); decide whether the agent actually accomplished the scenario from the transcript and tool calls.\n- Similar-sounding word substitutions (e.g. "ocean" for "OSHA") are STT ambiguity, not comprehension failure. The fix lives in STT keyword hints, custom vocabulary, or a prompt-level term list \u2014 not the agent\'s reasoning.\n- Surface only what the user can act on in their own agent\'s code or config \u2014 never `warnings[]` (infrastructure noise), Vent-side artifacts (caller wait modes, harness timing, internal pipeline quirks), or `cost_usd` unless asked.\n\nFor multi-call runs, lead with your own judgment of what happened across the calls (e.g. "3 of 4 did what they were supposed to; `cancel-appointment` never actually canceled"), not a parroted pass/fail count. Then cover each call with whatever depth it needs.\n';
 
 // src/skills/codex.md
-var codex_default = '# Vent - Voice Agent Calls\n\nUse Vent to verify real voice-agent behavior from the terminal.\n\n## When to Test\n\nVent is the voice CI gate for the agent. A non-trivial change that touches voice behavior is not "done" until the relevant Vent call has been run and you\'ve judged from its output that the change works. Auto-trigger a call after finishing the change \u2014 do not wait to be asked.\n\nNon-trivial means anything that can change what the caller hears, how the agent responds, what tools are called, how the call routes, or how audio timing behaves: prompt rewrites or sections (not a one-word tweak), tool schema or handler changes, state/memory logic, transfer logic, interruption handling, provider/audio config, platform integration code, and any bug fix for voice-agent behavior. One-line copy or comment edits do not need a call.\n\nBefore launching, check `.vent/runs/` for unresolved issues from prior runs (failing status, regressions, warnings, latency jumps). If any are still present and within the scope of the current task, fix them as part of this change, then run the call to verify both the new fix and the prior issues are resolved. Report unresolved prior issues that are out of scope rather than silently leaving them.\n\nDo not declare the task complete until you\'ve reviewed the call results \u2014 transcript, tool calls, observed behavior \u2014 and confirmed the change actually does what was intended. Vent\'s `status` and exit code only tell you whether the call ran end-to-end without a pipeline error; mission success is your judgment.\n\n## Autonomous Iteration\n\nYou can run a fix \u2192 Vent-call \u2192 fix \u2192 Vent-call loop within a single user request, doing many iterations before returning. This is genuinely useful for mechanical issues where the fix is high-confidence but the verification is slow.\n\nDefault: don\'t iterate autonomously. Run the relevant call after your change, surface findings, and let the user decide what\'s next \u2014 they stay in control of cost and scope.\n\nTrigger autonomous iteration when either:\n- The user explicitly asks for it ("iterate until it works", "keep going", "autonomous mode", "fix everything").\n- You judge it\'s clearly worth it: the change is well-scoped, the failure mode is mechanical (tool schema, registry, prompt phrasing), and you have a concrete plan for the next attempt. If you\'d be guessing at the next attempt, stop and ask.\n\nCap iterations at ~5 unless the user gave a higher bound. If the same fix attempt fails twice, or the failure mode keeps shifting between attempts, stop and report \u2014 you\'re thrashing.\n\nThe user may not know autonomous iteration is on the table. When you suspect a likely-multi-cycle issue, offer it once before starting solo (e.g. "I can iterate on this autonomously, otherwise I\'ll stop here for your review").\n\n## Codex Execution\n\nCodex can run shell tool calls concurrently, so run multiple Vent calls as separate shell commands in parallel. Do not combine them with `&`.\n\nFor multiple calls from one suite, run each named call with `--call <name>` as its own parallel shell tool call:\n\n```bash\nnpx vent-hq run -f .vent/suite.vapi.json --call happy-path\nnpx vent-hq run -f .vent/suite.vapi.json --call tool-path\n```\n\nUse a 5-minute shell-tool timeout (`300000` ms) on Vent run commands so normal calls are not killed by the default 2-minute Bash timeout. This is not backgrounding; wait for stdout/results before ending your response. Use the JSON returned by `npx vent-hq run` directly; do not call `vent status` unless checking an older run.\n\n## Workflow\n\n1. Identify the behavior under test. Read enough of the agent codebase to understand its system prompt, tools, handlers, routes, provider config, platform wiring, and expected handoffs.\n2. Reuse an existing `.vent/suite.<adapter>.json` when possible. If `.vent/` contains multiple suites, inspect `connection.adapter` and report which suite file produced the result.\n3. Create or update a suite only when the existing calls do not cover the changed behavior. Name calls after real flows, for example `reschedule-appointment`, not `call-1`.\n4. If the suite uses `start_command`, start one shared local session first with `npx vent-hq agent start -f .vent/suite.<adapter>.json`, then pass `--session <session-id>` to each run. **For locally-run LiveKit agents: every run requires restarting the worker first, then waiting a full 60 seconds before submitting the call.** This is unconditional \u2014 every run, no exceptions. Skipping the wait fails with `did not publish audio track` even though the worker is up. Hosted LiveKit Cloud agents don\'t need this; just run normally.\n5. Pick which call(s) to run based on the change. Fixed bug: replay the failing scenario. Changed tool: include a call that triggers that tool. Prompt or routing change: include the relevant happy path and any important edge path.\n6. Compare against the previous JSON in `.vent/runs/` when validating a fix or regression. Check status flips, latency jumps, tool-call success drops, cost jumps, and transcript divergence. Correlate with `git diff` between saved `git_sha` values when available; skip if no previous run exists.\n\n## Saved Runs\n\nAfter every run, Vent writes the full result JSON to `.vent/runs/`. Shape:\n\n```jsonc\n{\n  "run_id": "...",\n  "timestamp": "2026-04-21T...Z",\n  "git_sha": "...",\n  "summary": { "calls_total": 2, "total_duration_ms": 12345, "total_cost_usd": 0.01 },\n  "call_results": [\n    { "name": "happy-path", "status": "completed", "duration_ms": 6123, "transcript": [], "observed_tool_calls": [], "metrics": { "latency_p50_ms": 420, "latency_p95_ms": 980 }, "cost_usd": 0.004 }\n  ]\n}\n```\n\nWhen comparing against a prior run (Workflow step 6), inspect these paths:\n\n- Run-completion status flips: `call_results[i].status` (this only reflects whether the call ran cleanly through the pipeline, not whether the agent accomplished the goal \u2014 judge that from the transcript)\n- Latency: `call_results[i].metrics.latency_p50_ms` or `latency_p95_ms` increased >20%\n- Tool calls: count of `call_results[i].observed_tool_calls[].successful` dropped\n- Cost: `summary.total_cost_usd` or `call_results[i].cost_usd` increased >30%\n- Transcript: `call_results[i].transcript` diverged in semantic content (ignore STT noise)\n\n## Commands\n\n```bash\nnpx vent-hq init                                                                         # First-time setup: autonomous auth, access token generation, skill install, and minimal starter suite\nnpx vent-hq login                                                                        # Log in to an existing account and save credentials\nnpx vent-hq run -f .vent/suite.<adapter>.json                                            # Run the only call in a suite, or error if the suite has multiple calls\nnpx vent-hq run -f .vent/suite.<adapter>.json --call happy-path                          # Run one named call from a multi-call suite\nnpx vent-hq run -f .vent/suite.<adapter>.json --call happy-path --session <session-id>   # Run one named call through an existing local relay session\nnpx vent-hq run -f .vent/suite.<adapter>.json --call happy-path --verbose                # Run one named call with verbose debug fields\nnpx vent-hq stop <run-id>                                                                # Cancel a queued or running run\nnpx vent-hq status <run-id>                                                              # Fetch results for a previous run\nnpx vent-hq status <run-id> --verbose                                                    # Fetch previous run results with verbose debug fields\nnpx vent-hq agent start -f .vent/suite.<adapter>.json                                    # Start a shared local relay session for suites that use start_command\nnpx vent-hq agent stop <session-id>                                                      # Stop a shared local relay session\n```\n\nIf `~/.vent/credentials` is missing and `VENT_ACCESS_TOKEN` is not set, run `npx vent-hq init`. For an existing account, run `npx vent-hq login` or set `VENT_ACCESS_TOKEN`.\n\n## Suite Config\n\nSuites live in `.vent/suite.<adapter>.json`. `connection` is declared once per suite. `calls` is a named map, and each key becomes the call name used with `--call`.\n\nLocal websocket suite:\n\n```json\n{\n  "connection": {\n    "adapter": "websocket",\n    "start_command": "npm run start",\n    "health_endpoint": "/health",\n    "agent_port": 3001\n  },\n  "calls": {\n    "happy-path": {\n      "caller_prompt": "You are Maria calling to reschedule her appointment to next Tuesday.",\n      "max_turns": 8,\n      "silence_threshold_ms": 1200,\n      "audio_actions": [\n        { "action": "interrupt", "at_turn": 3, "prompt": "Just give me the earliest one." }\n      ]\n    }\n  }\n}\n```\n\nPlatform-direct suite:\n\n```json\n{\n  "connection": {\n    "adapter": "vapi",\n    "platform": { "provider": "vapi" }\n  },\n  "calls": {\n    "happy-path": {\n      "caller_prompt": "You are Maria calling to reschedule her appointment to next Tuesday.",\n      "max_turns": 8\n    }\n  }\n}\n```\n\nWrite `caller_prompt` as a realistic caller with a name, goal, mood, constraints, and conditional behavior. Set `max_turns` based on flow complexity: FAQ `4-6`, booking or tool use `8-12`, complex flows `12-20`.\n\nCall fields:\n\n- `caller_prompt` and `max_turns` are required.\n- `silence_threshold_ms` must be `200-10000`. Common ranges: FAQ `800-1200`, tool calls `2000-3000`, complex reasoning `3000-5000`.\n- `persona` supports `pace`, `clarity`, `disfluencies`, `cooperation`, `emotion`, `interruption_style`, `memory`, `intent_clarity`, and `confirmation_style`.\n- `audio_actions` supports `interrupt`, `inject_noise`, `split_sentence`, and `noise_on_caller`.\n- `caller_audio` supports noise, speed, speakerphone, mic distance, clarity, accent, packet loss, and jitter.\n- `language` is an ISO 639-1 code such as `en`, `es`, `fr`, `de`, `it`, `nl`, or `ja`.\n- `prosody: true` enables emotion analysis and requires Hume access.\n- Prefer explicit `audio_actions.interrupt` over `persona.interruption_style` for deterministic barge-in tests. `persona.interruption_style` is only a preplanned caller tendency.\n\n## Connections and Credentials\n\n### Adapter choice\n\nUse `websocket` for your own local or hosted runtime. Use `start_command` for local agents or `agent_url` for hosted custom endpoints. For `start_command` and `agent_url`, do not put Deepgram, ElevenLabs, OpenAI, or other agent runtime keys into Vent config unless the Vent adapter itself needs them \u2014 the tested agent owns its own runtime credentials.\n\nUse `vapi`, `retell`, `elevenlabs`, `bland`, or `livekit` for platform-direct testing. In this mode Vent itself talks to the provider on the user\'s behalf.\n\nVent provides `DEEPGRAM_API_KEY` and `ANTHROPIC_API_KEY` for its hosted caller/evaluation stack \u2014 those are Vent\'s, not the tested agent\'s.\n\n### Credential resolution\n\nIn platform-direct mode the CLI auto-resolves credentials from `.env.local`, `.env`, and the current shell environment. Do not run `source .env && export` before Vent commands. If you include credential fields in JSON, use the actual value, not the env var name. Do not manually author `platform_connection_id`; the CLI creates or updates the saved platform connection automatically.\n\nAuto-resolved env vars and JSON fields:\n\n- Vapi: `VAPI_API_KEY` -> `vapi_api_key`; `VAPI_ASSISTANT_ID` or `VAPI_AGENT_ID` -> `vapi_assistant_id`\n- Bland: `BLAND_API_KEY` -> `bland_api_key`; `BLAND_PATHWAY_ID` -> `bland_pathway_id`; `BLAND_PERSONA_ID` -> `persona_id`\n- LiveKit: `LIVEKIT_API_KEY` -> `livekit_api_key`; `LIVEKIT_API_SECRET` -> `livekit_api_secret`; `LIVEKIT_URL` -> `livekit_url`\n- Retell: `RETELL_API_KEY` -> `retell_api_key`; `RETELL_AGENT_ID` -> `retell_agent_id`\n- ElevenLabs: `ELEVENLABS_API_KEY` -> `elevenlabs_api_key`; `ELEVENLABS_AGENT_ID` -> `elevenlabs_agent_id`\n\n### Provider config\n\nUse existing provider config when possible: Vapi assistant, Retell agent, ElevenLabs agent, Bland pathway, or LiveKit agent. Bland uniquely supports inline config \u2014 `platform` may use `bland_pathway_id`, `persona_id`, or an inline `task` (with optional voice, model, and turn-handling overrides; see Bland\'s API docs for the full field list).\n\n### Concurrency\n\nWhen you fan out multiple Vent calls in parallel against the same provider (for example, running several named calls from one suite at once), respect the provider\'s per-account concurrency limit. Exceeding it makes calls queue or fail at the provider \u2014 Vent does not enforce these caps for you.\n\nRecord the limit as `max_concurrency` in the suite\'s `platform` block so it\'s visible on future runs. Ask the user which plan they\'re on if sizing matters; otherwise use the conservative default in bold.\n\n- **Vapi**: **10** included per account; reserved lines can be purchased self-serve; Enterprise is unlimited.\n- **Retell**: Pay-as-you-go includes **20**; Enterprise has no cap.\n- **Bland**: Start=**10**, Build=50, Scale=100, Enterprise=unlimited.\n- **ElevenLabs**: Free=**4**, Starter=6, Creator=10, Pro=20, Scale=30, Business=30. Burst pricing can temporarily allow up to 3x base.\n- **LiveKit Cloud**: Build=**5**, Ship=20, Scale=50 managed inference sessions (the usual gate for voice agents); agent-session concurrency can go higher (Scale up to 600).\n\n## WebSocket\n\nFor `adapter: "websocket"`, Vent sends binary 16-bit mono PCM audio over one websocket connection. Websocket text frames are optional JSON events. Audio-only websocket agents still work, but events improve turn detection and observability. Vent sends `{"type":"end-call"}` when the test is done.\n\nUseful websocket text frames:\n\n```jsonc\n{"type":"speech-update","status":"started"}\n{"type":"speech-update","status":"stopped"}\n{"type":"tool_call","name":"check_availability","arguments":{},"result":{},"successful":true,"duration_ms":150}\n{"type":"vent:timing","stt_ms":120,"llm_ms":450,"tts_ms":80}\n{"type":"vent:session","platform":"custom","provider_call_id":"call_123","provider_session_id":"session_abc"}\n{"type":"vent:call-metadata","call_metadata":{"recording_url":"https://...","cost_usd":0.12}}\n{"type":"vent:transcript","role":"caller","text":"I need to reschedule","turn_index":0}\n{"type":"vent:transfer","destination":"+15551234567","status":"attempted"}\n{"type":"vent:debug-url","label":"trace","url":"https://..."}\n{"type":"vent:warning","message":"provider warning","code":"provider_warning"}\n```\n\n`vent:session-report` is **not** handled by the websocket adapter \u2014 it\'s only consumed by the LiveKit helper. Do not emit it from a websocket agent.\n\nPlatform adapters capture tool calls automatically. Websocket agents must emit `tool_call` frames for tool observability. Platform adapters get component latency automatically. Websocket agents should emit `vent:timing` after each agent response when STT/LLM/TTS breakdown is available.\n\n## LiveKit\n\nBefore running LiveKit tests, install and add the Vent helper to the LiveKit agent entrypoint. Node: `npm install @vent-hq/livekit`, then call `instrumentLiveKitAgent({ ctx, session })`. Python: `pip install vent-livekit`, then call `instrument_livekit_agent(ctx=ctx, session=session)`.\n\nLiveKit direct mode requires the LiveKit Agents SDK. Custom LiveKit participants should use the websocket adapter with a relay. If the LiveKit agent registered with an explicit dispatch name, set `livekit_agent_name` in `platform`.\n\nLiveKit does not support multiple concurrent Vent calls against one agent process yet. Run LiveKit calls sequentially unless you intentionally start separate agent worker processes and route each call to its own process. For Node agents, that means separate Node.js processes. Do not treat parallel calls against a single LiveKit worker as a valid concurrency test until multi-call support is engineered.\n\nUse the LiveKit helper for observability; do not publish `vent:*` topics manually. Do not hand-roll `vent:session-report` from `ctx.addShutdownCallback`; after `room.disconnect()` it can fail with `engine is closed`. The helper captures SDK metrics, tool events, conversation items, usage, and close events. Native LiveKit `lk.transcription` and `lk.agent.state` provide transcript and agent-state timing.\n\nIf a LiveKit run fails with `agent did not speak` or `no speech detected`, kill the stale agent, wait 60 seconds, then restart once. Do not restart multiple times in quick succession \u2014 each restart leaves a stale registration that compounds the routing problem.\n\n## Vent Output\n\n`npx vent-hq run` returns one JSON result on stdout in non-TTY agent mode; it is not an SSE JSONL stream. Analyze that result directly. Exit codes: `0` = call ran end-to-end through the pipeline; `1` = pipeline-level failure (call did not complete cleanly); `2` = harness error. None of these is a judgment of whether the agent actually accomplished the scenario\'s goal \u2014 decide that yourself from the transcript, tool calls, and the scenario\'s expected behavior.\n\nAlways-present keys (value may be `null` for `name`/`error`, otherwise non-null): `name`, `status`, `caller_prompt`, `duration_ms`, `error`, `transcript`, `tool_calls`, `warnings`, `audio_actions`. Always-present keys with nullable value (when the underlying analysis did not run): `latency`, `component_latency`, `call_metadata`, `emotion` (requires `prosody: true`). Conditional key (absent unless requested): `debug` (only when `--verbose`). Branch on null before reading nested fields.\n\nTrigger `--verbose` when:\n- transcript accuracy looks wrong and you need `platform_transcript` to compare against Vent\'s STT\n- latency looks bad and you need per-turn or component-level breakdowns\n- interruption / barge-in behavior looks wrong and you need per-turn debug fields\n- tool-call execution looks inconsistent or missing and you need the raw observed timeline\n- the provider returned warnings or errors and you need provider-native artifacts in `debug.provider_metadata`\n\nSkip `--verbose` for normal call iteration \u2014 it adds noise to stdout for no benefit.\n\nIgnore minor STT mis-transcriptions in `transcript` text (e.g. `"check teach hat"` for `"check that"`, swapped homophones, missing question marks on short tails). These are streaming-STT artifacts, not agent bugs. Judge on semantic intent, not exact spelling. Only flag transcript quality when it prevents understanding what the agent actually said.\n\n`audio_actions` lists which turns had injected interrupts; check the agent\'s reply at the next turn to judge whether it acknowledged the barge-in or restarted from scratch. Overtalk needs the recording and is not evaluable from transcript text alone.\n\nFor transfers, `call_metadata.transfer_attempted` (provider claimed it tried) and `call_metadata.transfer_completed` (mechanically verified by Vent) can disagree \u2014 report both. Use `call_metadata.transfers[]` for destination, type, and per-attempt status.\n\n## Reporting Results\n\nBefore reporting, read the agent\'s code to locate where the observed behavior originates. If the issue is small and you can fix it, fix it and explain what you did \u2014 don\'t ask permission first.\n\nThen write whatever shape of report fits the call. No mandated structure. The report is for a voice-agent developer who wants to know: did my change work, and if not, what do I do next? Adapt the depth to the call \u2014 a clean pass with nothing to report needs little; a regression with a multi-layer cause needs more. Use a transcript excerpt when it helps the user see what actually happened.\n\nHard rules \u2014 these are about not leaking Vent\'s internals into a user-facing report:\n\n- Translate raw numbers into plain English. Users do not know what "p95 850ms" means; say "snappy throughout" or "noticeably sluggish, around 1.6 seconds with the LLM as the bottleneck."\n- Name the user\'s voice agent by platform on first mention (e.g. "the Vapi agent responded snappily throughout") so the user knows immediately which agent the observation is about. After that first mention, just call it "the agent" \u2014 don\'t repeat the platform name on every line.\n- Always include the recording from `call_metadata.recording_url` as an inline `[Recording](url)` link, placed in **one block at the very end of the report** \u2014 never sprinkled through the prose. For a single call, it\'s one link as the last line. For multi-call reports, the bottom block lists one link per call labeled by name (e.g. `reschedule-appointment: [Recording](url)`). Never paste a bare URL.\n- Mission success is your judgment. Vent does not emit a pass/fail verdict. The per-call `status` is only `"completed"` (call ran end-to-end through the pipeline) or `"error"` (pipeline-level failure), and the exit code only reflects the same. Decide whether the agent actually accomplished the scenario from the transcript and tool calls.\n- When the agent uses a similar-sounding but different word from what the caller said (e.g. "ocean" for "OSHA"), treat it as STT ambiguity in the agent\'s pipeline, not a comprehension failure. The fix lives in STT keyword hints, custom vocabulary, or a prompt-level term list \u2014 not the agent\'s reasoning.\n- Don\'t surface `warnings[]` (infrastructure noise). Don\'t surface Vent-side artifacts (caller wait modes, harness timing, internal pipeline quirks). Don\'t include `cost_usd` unless the user asks.\n- Surface only what the user can act on in their own agent\'s code or config.\n\nFor multi-call runs, lead with a short summary stating *your* judgment of what happened across the calls (e.g. "3 of 4 did what they were supposed to; `cancel-appointment` never actually canceled"), not a parroted Vent pass/fail count. Then cover each call with whatever depth it needs.\n';
+var codex_default = '# Vent - Voice Agent Calls\n\n## When to Test\n\nVent is the voice CI gate. Auto-trigger a call after any non-trivial voice-affecting change \u2014 don\'t wait to be asked. Non-trivial means anything that affects what the caller hears, how the agent responds, what tools are called, how the call routes, or audio timing: prompt rewrites or sections (not one-word tweaks), tool schema or handler changes, state/memory logic, transfer logic, interruption handling, provider/audio config, platform integration, and any voice-behavior bug fix. One-line copy or comment edits don\'t need a call.\n\nBefore launching, scan `.vent/runs/` for unresolved issues from prior runs (failing status, regressions, warnings, latency jumps); fix in-scope ones as part of this change and verify they\'re resolved by the new run, surface out-of-scope ones rather than silently leaving them. The task is not done until you\'ve reviewed the transcript, tool calls, and observed behavior and judged that the change works \u2014 Vent\'s `status` and exit code only reflect pipeline completion, not mission success.\n\n## Autonomous Iteration\n\nYou can run a fix \u2192 Vent-call \u2192 fix \u2192 Vent-call loop in one user request \u2014 useful for mechanical issues where the fix is high-confidence but verification is slow. Default off: run the relevant call once, surface findings, let the user decide. Trigger autonomous iteration only when the user explicitly asks ("iterate until it works", "autonomous mode", "fix everything"), or when the change is well-scoped, the failure mode is mechanical (tool schema, registry, prompt phrasing), and you have a concrete plan for the next attempt \u2014 if you\'d be guessing, stop and ask.\n\nStop and report if the same fix fails twice, the failure mode shifts between attempts, or you can\'t justify the next call against its provider cost \u2014 each call spends real money and provider quota. The user may not know autonomous iteration exists, especially early in their Vent usage \u2014 proactively surface the option the first time you suspect a likely-multi-cycle issue (e.g. "this is the kind of thing I could iterate on autonomously if you want, otherwise I\'ll run the call once and stop for your review").\n\n## Codex Execution\n\nUse a 5-minute shell-tool timeout (`300000` ms) on Vent run commands so normal calls are not killed by the default 2-minute Bash timeout. This is not backgrounding; wait for stdout/results before ending your response. Use the JSON returned by `npx vent-hq run` directly; do not call `vent status` unless checking an older run.\n\nCodex can run shell tool calls concurrently \u2014 for multiple calls from one suite, run each named call as its own parallel shell tool call (do not combine them with `&`):\n\n```bash\nnpx vent-hq run -f .vent/suite.vapi.json --call happy-path\nnpx vent-hq run -f .vent/suite.vapi.json --call tool-path\n```\n\n## Workflow\n\n1. Identify the behavior under test. Read enough of the agent codebase to understand its system prompt, tools, handlers, routes, provider config, platform wiring, and expected handoffs.\n2. Reuse an existing `.vent/suite.<adapter>.json` when possible. If `.vent/` contains multiple suites, inspect `connection.adapter` and report which suite file produced the result.\n3. Create or update a suite only when the existing calls do not cover the changed behavior. Name calls after real flows, for example `reschedule-appointment`, not `call-1`.\n4. If the suite uses `start_command`, start one shared local session first with `npx vent-hq agent start -f .vent/suite.<adapter>.json`, then pass `--session <session-id>` to each run.\n\n   **For locally-run LiveKit agents: every run requires killing *all* workers, starting one fresh worker, and waiting a full 60 seconds before submitting.** Unconditional \u2014 LiveKit Cloud round-robins across registered workers, so a single survivor with a dead inference subprocess fails ~N-1 of N calls. Don\'t rely on `pkill -f <path-pattern>`; bare command lines like `node --import tsx agent.ts dev` won\'t match a path filter. Use `ps aux | grep -E "node.*agent\\.ts|@livekit/agents.*ipc"`, `kill -9` by PID, re-run `ps` to confirm zero survivors, then start the fresh worker. Skipping the 60s wait fails with `did not publish audio track`; if that error appears alongside `Error [ERR_IPC_CHANNEL_CLOSED] from InferenceProcExecutor.doInference` in the agent log right after a "running EOU detection" line, that\'s a straggler \u2014 redo the kill sweep. Hosted LiveKit Cloud agents don\'t need any of this; run normally.\n5. Pick which call(s) to run based on the change. Fixed bug: replay the failing scenario. Changed tool: include a call that triggers that tool. Prompt or routing change: include the relevant happy path and any important edge path.\n6. Compare against the previous JSON in `.vent/runs/` when validating a fix or regression. Check status flips, latency jumps, tool-call success drops, cost jumps, and transcript divergence. Correlate with `git diff` between saved `git_sha` values when available; skip if no previous run exists.\n\n## Commands\n\n```bash\nnpx vent-hq init                                  # First-time setup (auth + skill install + starter suite)\nnpx vent-hq login                                 # Log in to existing account\nnpx vent-hq run -f .vent/suite.X.json             # Run a single-call suite\nnpx vent-hq run -f .vent/suite.X.json --call NAME # Run one named call from a multi-call suite\nnpx vent-hq run ... --session <session-id>        # Add to any run; routes through an existing local relay session\nnpx vent-hq run ... --verbose                     # Add to any run or status; include verbose debug fields\nnpx vent-hq stop <run-id>                         # Cancel a queued or running run\nnpx vent-hq status <run-id>                       # Fetch results for a previous run\nnpx vent-hq agent start -f .vent/suite.X.json     # Start a shared local relay session\nnpx vent-hq agent stop <session-id>               # Stop a shared local relay session\n```\n\nIf `~/.vent/credentials` is missing and `VENT_ACCESS_TOKEN` is not set, run `npx vent-hq init`. For an existing account, run `npx vent-hq login` or set `VENT_ACCESS_TOKEN`.\n\n## Suite Config\n\nSuites live in `.vent/suite.<adapter>.json`. `connection` is declared once per suite. `calls` is a named map, and each key becomes the call name used with `--call`.\n\nLocal websocket suite:\n\n```json\n{\n  "connection": {\n    "adapter": "websocket",\n    "start_command": "npm run start",\n    "health_endpoint": "/health",\n    "agent_port": 3001\n  },\n  "calls": {\n    "happy-path": {\n      "caller_prompt": "You are Maria calling to reschedule her appointment to next Tuesday.",\n      "max_turns": 8,\n      "silence_threshold_ms": 1200,\n      "audio_actions": [\n        { "action": "interrupt", "at_turn": 3, "prompt": "Just give me the earliest one." }\n      ]\n    }\n  }\n}\n```\n\nPlatform-direct suite:\n\n```json\n{\n  "connection": {\n    "adapter": "vapi",\n    "platform": { "provider": "vapi" }\n  },\n  "calls": {\n    "happy-path": {\n      "caller_prompt": "You are Maria calling to reschedule her appointment to next Tuesday.",\n      "max_turns": 8\n    }\n  }\n}\n```\n\nWrite `caller_prompt` as a realistic caller with a name, goal, mood, constraints, and conditional behavior. Set `max_turns` based on flow complexity: FAQ `4-6`, booking or tool use `8-12`, complex flows `12-20`.\n\nCall fields:\n\n- `caller_prompt` and `max_turns` are required.\n- `silence_threshold_ms` must be `200-10000`. Common ranges: FAQ `800-1200`, tool calls `2000-3000`, complex reasoning `3000-5000`.\n- `persona` supports `pace`, `clarity`, `disfluencies`, `cooperation`, `emotion`, `interruption_style`, `memory`, `intent_clarity`, and `confirmation_style`.\n- `audio_actions` supports `interrupt`, `inject_noise`, `split_sentence`, and `noise_on_caller`.\n- `caller_audio` supports noise, speed, speakerphone, mic distance, clarity, accent, packet loss, and jitter.\n- `language` is an ISO 639-1 code such as `en`, `es`, `fr`, `de`, `it`, `nl`, or `ja`.\n- `prosody: true` enables emotion analysis and requires Hume access.\n- Prefer explicit `audio_actions.interrupt` over `persona.interruption_style` for deterministic barge-in tests. `persona.interruption_style` is only a preplanned caller tendency.\n\n## Connections and Credentials\n\n### Adapter choice\n\nUse `websocket` for your own local or hosted runtime. Use `start_command` for local agents or `agent_url` for hosted custom endpoints. For `start_command` and `agent_url`, do not put Deepgram, ElevenLabs, OpenAI, or other agent runtime keys into Vent config unless the Vent adapter itself needs them \u2014 the tested agent owns its own runtime credentials.\n\nUse `vapi`, `retell`, `elevenlabs`, `bland`, or `livekit` for platform-direct testing. In this mode Vent itself talks to the provider on the user\'s behalf.\n\nVent provides `DEEPGRAM_API_KEY` and `ANTHROPIC_API_KEY` for its hosted caller/evaluation stack \u2014 those are Vent\'s, not the tested agent\'s.\n\n### Credential resolution\n\nIn platform-direct mode the CLI auto-resolves credentials from `.env.local`, `.env`, and the current shell environment. Do not run `source .env && export` before Vent commands. If you include credential fields in JSON, use the actual value, not the env var name. Do not manually author `platform_connection_id`; the CLI creates or updates the saved platform connection automatically.\n\nAuto-resolved env vars and JSON fields:\n\n- Vapi: `VAPI_API_KEY` -> `vapi_api_key`; `VAPI_ASSISTANT_ID` or `VAPI_AGENT_ID` -> `vapi_assistant_id`\n- Bland: `BLAND_API_KEY` -> `bland_api_key`; `BLAND_PATHWAY_ID` -> `bland_pathway_id`; `BLAND_PERSONA_ID` -> `persona_id`\n- LiveKit: `LIVEKIT_API_KEY` -> `livekit_api_key`; `LIVEKIT_API_SECRET` -> `livekit_api_secret`; `LIVEKIT_URL` -> `livekit_url`\n- Retell: `RETELL_API_KEY` -> `retell_api_key`; `RETELL_AGENT_ID` -> `retell_agent_id`\n- ElevenLabs: `ELEVENLABS_API_KEY` -> `elevenlabs_api_key`; `ELEVENLABS_AGENT_ID` -> `elevenlabs_agent_id`\n\n### Provider config\n\nUse existing provider config when possible: Vapi assistant, Retell agent, ElevenLabs agent, Bland pathway, or LiveKit agent. Bland uniquely supports inline config \u2014 `platform` may use `bland_pathway_id`, `persona_id`, or an inline `task` (with optional voice, model, and turn-handling overrides; see Bland\'s API docs for the full field list).\n\n### Concurrency\n\nWhen you fan out multiple Vent calls in parallel against the same provider (for example, running several named calls from one suite at once), respect the provider\'s per-account concurrency limit. Exceeding it makes calls queue or fail at the provider \u2014 Vent does not enforce these caps for you.\n\nRecord the limit as `max_concurrency` in the suite\'s `platform` block so it\'s visible on future runs. Ask the user which plan they\'re on if sizing matters; otherwise use the conservative default in bold.\n\n- **Vapi**: **10** included per account; reserved lines can be purchased self-serve; Enterprise is unlimited.\n- **Retell**: Pay-as-you-go includes **20**; Enterprise has no cap.\n- **Bland**: Start=**10**, Build=50, Scale=100, Enterprise=unlimited.\n- **ElevenLabs**: Free=**4**, Starter=6, Creator=10, Pro=20, Scale=30, Business=30. Burst pricing can temporarily allow up to 3x base.\n- **LiveKit Cloud**: Build=**5**, Ship=20, Scale=50 managed inference sessions (the usual gate for voice agents); agent-session concurrency can go higher (Scale up to 600).\n\n## WebSocket\n\nFor `adapter: "websocket"`, Vent sends binary 16-bit mono PCM audio over one websocket connection. Websocket text frames are optional JSON events. Audio-only websocket agents still work, but events improve turn detection and observability. Vent sends `{"type":"end-call"}` when the test is done.\n\nUseful websocket text frames:\n\n```jsonc\n{"type":"speech-update","status":"started"}\n{"type":"speech-update","status":"stopped"}\n{"type":"tool_call","name":"check_availability","arguments":{},"result":{},"successful":true,"duration_ms":150}\n{"type":"vent:timing","stt_ms":120,"llm_ms":450,"tts_ms":80}\n{"type":"vent:session","platform":"custom","provider_call_id":"call_123","provider_session_id":"session_abc"}\n{"type":"vent:call-metadata","call_metadata":{"recording_url":"https://...","cost_usd":0.12}}\n{"type":"vent:transcript","role":"caller","text":"I need to reschedule","turn_index":0}\n{"type":"vent:transfer","destination":"+15551234567","status":"attempted"}\n{"type":"vent:debug-url","label":"trace","url":"https://..."}\n{"type":"vent:warning","message":"provider warning","code":"provider_warning"}\n```\n\n`vent:session-report` is **not** handled by the websocket adapter \u2014 it\'s only consumed by the LiveKit helper. Do not emit it from a websocket agent.\n\nPlatform adapters capture tool calls automatically. Websocket agents must emit `tool_call` frames for tool observability. Platform adapters get component latency automatically. Websocket agents should emit `vent:timing` after each agent response when STT/LLM/TTS breakdown is available.\n\n## LiveKit\n\nBefore running LiveKit tests, install and add the Vent helper to the LiveKit agent entrypoint. Node: `npm install @vent-hq/livekit`, then call `instrumentLiveKitAgent({ ctx, session })`. Python: `pip install vent-livekit`, then call `instrument_livekit_agent(ctx=ctx, session=session)`.\n\nLiveKit direct mode requires the LiveKit Agents SDK. Custom LiveKit participants should use the websocket adapter with a relay. If the LiveKit agent registered with an explicit dispatch name, set `livekit_agent_name` in `platform`.\n\nLiveKit does not support multiple concurrent Vent calls against one agent process yet. Run LiveKit calls sequentially unless you intentionally start separate agent worker processes and route each call to its own process. For Node agents, that means separate Node.js processes. Do not treat parallel calls against a single LiveKit worker as a valid concurrency test until multi-call support is engineered.\n\nUse the LiveKit helper for observability; do not publish `vent:*` topics manually. Do not hand-roll `vent:session-report` from `ctx.addShutdownCallback`; after `room.disconnect()` it can fail with `engine is closed`. The helper captures SDK metrics, tool events, conversation items, usage, and close events. Native LiveKit `lk.transcription` and `lk.agent.state` provide transcript and agent-state timing.\n\n## Output\n\n### Live result\n\n`npx vent-hq run` returns a single JSON result on stdout in non-TTY mode (not an SSE JSONL stream). Exit codes: `0` = call ran through the pipeline; `1` = pipeline-level failure; `2` = harness error.\n\nMost result fields are always present; `latency`, `component_latency`, `call_metadata`, and `emotion` may be `null` when the underlying analysis didn\'t run; `debug` is absent without `--verbose`. Branch on null before reading nested fields. Use `--verbose` only when the default doesn\'t explain a failure \u2014 when you need `platform_transcript` (to check Vent\'s STT), per-turn or component-level latency breakdowns, the raw tool-call timeline, or provider-native artifacts in `debug.provider_metadata`. Otherwise skip \u2014 it just adds noise.\n\nIgnore minor STT mis-transcriptions in `transcript` (e.g. `"check teach hat"` for `"check that"`, homophones, missing question marks on short tails) \u2014 they\'re streaming-STT artifacts, not agent bugs. Judge on semantic intent.\n\n`audio_actions` lists turns with injected interrupts; check the next turn to judge whether the agent acknowledged or restarted. Overtalk needs the recording and isn\'t evaluable from text alone.\n\nFor transfers: `call_metadata.transfer_attempted` (provider claimed) and `transfer_completed` (Vent-verified) can disagree \u2014 report both. `transfers[]` carries destination, type, and per-attempt status.\n\n### Saved history\n\nAfter every run, Vent writes the full result JSON to `.vent/runs/`. Shape:\n\n```jsonc\n{\n  "run_id": "...",\n  "timestamp": "2026-04-21T...Z",\n  "git_sha": "...",\n  "summary": { "calls_total": 2, "total_duration_ms": 12345, "total_cost_usd": 0.01 },\n  "call_results": [\n    { "name": "happy-path", "status": "completed", "duration_ms": 6123, "transcript": [], "observed_tool_calls": [], "metrics": { "latency_p50_ms": 420, "latency_p95_ms": 980 }, "cost_usd": 0.004 }\n  ]\n}\n```\n\nWhen comparing against a prior run (Workflow step 6), inspect:\n\n- Run-completion status flips: `call_results[i].status` (pipeline-only \u2014 judge mission success from the transcript)\n- Latency: `call_results[i].metrics.latency_p50_ms` or `latency_p95_ms` increased >20%\n- Tool calls: count of `call_results[i].observed_tool_calls[].successful` dropped\n- Cost: `summary.total_cost_usd` or `call_results[i].cost_usd` increased >30%\n- Transcript: `call_results[i].transcript` diverged in semantic content (ignore STT noise)\n\n## Reporting Results\n\nBefore reporting, read the agent\'s code to locate where the observed behavior originates. If the issue is small and you can fix it, fix it and explain what you did \u2014 don\'t ask permission first.\n\nAdapt the report shape to the call \u2014 a clean pass needs little, a regression with a multi-layer cause needs more. Use a transcript excerpt when it helps the user see what happened.\n\nHard rules:\n\n- Pair raw numbers with their plain-English meaning \u2014 don\'t drop the number, but don\'t leave it unexplained. E.g. "p95 latency was 850ms, which is snappy and well within natural conversational pacing" or "p95 hit 1.6 seconds with the LLM as the bottleneck \u2014 noticeably sluggish to a caller."\n- Name the user\'s voice agent by platform on first mention (e.g. "the Vapi agent responded snappily throughout") so the user knows immediately which agent the observation is about. After that, just say "the agent" \u2014 don\'t repeat the platform name on every line.\n- Always include the recording from `call_metadata.recording_url` as an inline `[Recording](url)` link, placed in **one block at the very end of the report** \u2014 never sprinkled through the prose. Single call: one link as the last line. Multi-call: one labeled link per call (e.g. `reschedule-appointment: [Recording](url)`). Never paste a bare URL.\n- Mission success is your judgment, not Vent\'s. The per-call `status` is only `"completed"` (pipeline ran) or `"error"` (pipeline failed); decide whether the agent actually accomplished the scenario from the transcript and tool calls.\n- Similar-sounding word substitutions (e.g. "ocean" for "OSHA") are STT ambiguity, not comprehension failure. The fix lives in STT keyword hints, custom vocabulary, or a prompt-level term list \u2014 not the agent\'s reasoning.\n- Surface only what the user can act on in their own agent\'s code or config \u2014 never `warnings[]` (infrastructure noise), Vent-side artifacts (caller wait modes, harness timing, internal pipeline quirks), or `cost_usd` unless asked.\n\nFor multi-call runs, lead with your own judgment of what happened across the calls (e.g. "3 of 4 did what they were supposed to; `cancel-appointment` never actually canceled"), not a parroted pass/fail count. Then cover each call with whatever depth it needs.\n';
 
 // src/lib/setup.ts
 var SUITE_SCAFFOLD = JSON.stringify(
@@ -6183,7 +6183,7 @@ async function main() {
     return 0;
   }
   if (command === "--version" || command === "-v") {
-    const pkg = await import("./package-KA6XHZLP.mjs");
+    const pkg = await import("./package-MHC6VAGU.mjs");
     console.log(`vent-hq ${pkg.default.version}`);
     return 0;
   }

package/dist/{package-KA6XHZLP.mjs → package-MHC6VAGU.mjs}

@@ -4,7 +4,7 @@ import "./chunk-XYDL7GY6.mjs";
 // package.json
 var package_default = {
   name: "vent-hq",
-  version: "0.10.5",
+  version: "0.10.6",
   type: "module",
   description: "Vent CLI \u2014 CI/CD for voice AI agents",
   bin: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vent-hq",
-  "version": "0.10.5",
+  "version": "0.10.6",
   "type": "module",
   "description": "Vent CLI — CI/CD for voice AI agents",
   "bin": {