xwave

# xwave AI JSON Interface This skill is for AI agents using `xwave ai ...` as a structured waveform fact API. Prefer the AI JSON entry point over the human CLI whenever you need machine-readable output, deterministic errors, or multi-step debug evidence. Human-oriented legacy CLI details were moved to [references/cli-reference.md](references/cli-reference.md). Load that file only when the user explicitly asks about non-AI command syntax. ## Entry Point Use one of these forms: ```bash tools/xwave-env ai query request.json tools/xwave-env ai query - tools/xwave-env ai query --json '{"api_version":"xwave.ai.v1","action":"value.at","target":{"fsdb":"waves.fsdb","auto_open":true},"args":{"signal":"top.clk","time":"10ns"}}' tools/xwave-env ai query --json '{"api_version":"xwave.ai.v1","action":"cursor.set","target":{"session_id":"case_a"},"args":{"name":"deadlock","time":"120340ns","note":"stall start"}}' tools/xwave-env ai query --json '{"api_version":"xwave.ai.v1","action":"value.at","target":{"session_id":"case_a"},"args":{"signal":"top.ready","at":"@deadlock-20ns","format":"hex"}}' tools/xwave-env ai schema tools/xwave-env ai actions ``` ## Output Verbosity Important: `xwave ai query` defaults to compact output. Compact output deliberately omits `tool`, `session`, empty `warnings`, empty `suggested_next_actions`, and `meta.elapsed_ms`. Do not assume those fields exist unless you request them. Use compact for normal AI workflows: ```json {"output":{"verbosity":"compact"}} ``` Use full when maintaining older scripts or discovering exact response fields: ```json {"output":{"verbosity":"full"}} ``` Use debug when diagnosing session/daemon/socket/FSDB fingerprint issues: ```json {"output":{"verbosity":"debug"}} ``` Errors still include structured `error.code/message`, and non-empty recovery hints remain present in compact output. AI value objects are intentionally minimal everywhere: `{"value":"...", "known":true|false}`. Do not expect `text`, `bits`, `hex`, `unsigned`, `signed`, or `unknown_reason`; choose the string representation with request `format`. For scripted extraction, pipe JSON output into `python3` instead of parsing human text. This is the recommended way for AI agents to pull specific fields or compute custom statistics: ```bash tools/xwave-env ai query --json '{"api_version":"xwave.ai.v1","action":"session.list"}' \ | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d["ok"], d.get("summary", {}))' ``` For larger summaries, keep the xwave query bounded and do the aggregation in Python: ```bash tools/xwave-env ai query --json '{"api_version":"xwave.ai.v1","action":"event.export","target":{"session_id":"case_a"},"args":{"name":"if0","expr":"valid && !ready","time_range":{"begin":"0ns","end":"100us"}},"limits":{"max_rows":1000}}' \ | python3 -c 'import json,sys; d=json.load(sys.stdin); rows=d.get("data",{}).get("events",[]); print(len(rows))' ``` For event counts or grouped counts, prefer built-in aggregation over exporting all rows: ```bash tools/xwave-env ai query --json '{"api_version":"xwave.ai.v1","action":"event.export","target":{"session_id":"case_a"},"args":{"name":"if0","expr":"valid && ready","time_range":{"begin":"0ns","end":"100us"},"aggregate":{"count":true,"group_by":["qid"],"events":false}}}' ``` Request envelope: ```json { "api_version": "xwave.ai.v1", "request_id": "optional-id", "action": "value.at", "target": { "fsdb": "/path/to/waves.fsdb", "auto_open": true }, "args": {}, "limits": { "max_rows": 1000, "max_events": 1000, "max_samples": 1000000 }, "output": { "verbosity": "compact" } } ``` Response envelope always contains: ```text compact: ok/action plus non-empty summary/data/findings/error/suggested_next_actions/meta.truncated full/debug: ok/action/session/summary/data/findings/suggested_next_actions/warnings/error/meta ``` Only `ok/action/error` and action-specific key data should be treated as always relevant. Field presence depends on `output.verbosity`; compact output will not include session/meta/tool scaffolding. Field names inside `summary`, `data`, and `findings` are action-specific and may differ by action. Do not guess detailed keys such as latency subfields from memory. For a field dictionary and extraction guidance, see [references/ai-response-dictionary.md](references/ai-response-dictionary.md). For exact fields on a specific build and FSDB, run `tools/xwave-env ai schema` when available, or issue a small bounded query and inspect the returned JSON before writing extraction code. AI usage rules: - Start with `session.open` for repeated work, then use `target.session_id` as a string. - For one-shot queries, use `target.fsdb + auto_open:true`. - Always inspect `ok` and `error.code`; do not parse human text. - Prefer `python3 -c 'import json,sys; ...'` pipelines for extracting fields or computing statistics from `xwave ai query` output. - Use `cursor.set` after finding an important event time, then use `@name`, `@name-20ns`, `@name+5ns`, `@name-10cycle(top.clk)`, or active cursor forms such as `@-10ns` in later time fields. - Time fields accept absolute TimeSpec strings directly. Cycle offsets use real FSDB clock edges: `cycle(clk)` means posedge, and `posedge(clk)` / `negedge(clk)` choose the edge explicitly. - For range actions, prefer `around/before/after` when investigating context around a cursor, for example `{"around":"@deadlock","before":"100cycle(top.clk)","after":"20cycle(top.clk)"}`. - Treat value `known:false`, `status:"unknown"`, and `pass:null` as inconclusive waveform facts, not failures. - Use `scope.list` after `SIGNAL_NOT_FOUND`. - Use `limits.max_rows/max_events/max_samples` for broad scans. - Load APB/AXI/Event configs before protocol or event actions. - Runtime state and persisted configs live under `~/.xwave/`: `registry.json` plus `sessions/<hashed-session-dir>/session.json`, `endpoint.json`, `socket`, `debug.log`, `lists.json`, `apb.json`, `axi.json`, `events.json`, and `cursors.json`. - Transport defaults to UDS. For LSF or multi-host clients, open with `args.transport:"tcp"` and a reachable `bind_host`; keep `port:0` unless the user explicitly needs a fixed port. The daemon writes the actual auto-assigned TCP port to `endpoint.json`, so later AI requests still only need `target.session_id`. ## Session Actions ### `session.open` Open a named session for an FSDB. The session name is required, is the real session id, and is reused by every later `target.session_id` field. Names may be up to 256 characters and may contain letters, digits, `_`, `.`, and `-`; duplicate names fail. Transport defaults to `uds`. Use `args.transport:"tcp"` for TCP; TCP ports are automatically assigned when `port` is omitted or `0`, and the actual endpoint is stored in `~/.xwave/sessions/<hashed-session-dir>/endpoint.json`. ```json {"api_version":"xwave.ai.v1","action":"session.open","target":{"fsdb":"/path/to/waves.fsdb"},"args":{"name":"case_a"}} {"api_version":"xwave.ai.v1","action":"session.open","target":{"fsdb":"/path/to/waves.fsdb"},"args":{"name":"case_tcp","transport":"tcp","bind_host":"127.0.0.1","port":0}} ``` ### `session.list` List known sessions. Use before reusing an existing session. ```json {"api_version":"xwave.ai.v1","action":"session.list"} ``` ### `session.doctor` Check daemon, transport endpoint, socket/PID, FSDB fingerprint, and health for a session. ```json {"api_version":"xwave.ai.v1","action":"session.doctor","target":{"session_id":"case_a"}} ``` ### `session.gc` Clean stale or idle sessions. ```json {"api_version":"xwave.ai.v1","action":"session.gc"} ``` ### `session.kill` Stop one session or all sessions. ```json {"api_version":"xwave.ai.v1","action":"session.kill","args":{"id":"all"}} ``` ## Cursor Actions Cursor actions store named session-local times. Use them when a debug flow has a key event time and later queries need context before or after that point. All later time fields can use `@name`, `@name-20ns`, `@name+5ns`, `@name-10cycle(top.clk)`, `@-10ns`, or `@+5ns`. ### `cursor.set` Create or replace a cursor. The response includes `data.resolved_time`, so use that as the canonical time for evidence. ```json {"api_version":"xwave.ai.v1","action":"cursor.set","target":{"session_id":"case_a"},"args":{"name":"deadlock","time":"120340ns","note":"rready stall starts"}} ``` ### `cursor.get` Fetch one cursor. ```json {"api_version":"xwave.ai.v1","action":"cursor.get","target":{"session_id":"case_a"},"args":{"name":"deadlock"}} ``` ### `cursor.list` List cursors and the active cursor. ```json {"api_version":"xwave.ai.v1","action":"cursor.list","target":{"session_id":"case_a"}} ``` ### `cursor.use` Set the active cursor, enabling short forms such as `@-20ns`. ```json {"api_version":"xwave.ai.v1","action":"cursor.use","target":{"session_id":"case_a"},"args":{"name":"deadlock"}} ``` ### `cursor.delete` Delete a cursor. ```json {"api_version":"xwave.ai.v1","action":"cursor.delete","target":{"session_id":"case_a"},"args":{"name":"deadlock"}} ``` ## Scope And Value Actions ### `scope.list` List available FSDB signals under a scope. Use this to recover from missing or ambiguous paths. ```json {"api_version":"xwave.ai.v1","action":"scope.list","target":{"session_id":"case_a"},"args":{"path":"top.u_dut","recursive":true},"limits":{"max_rows":200}} ``` ### `value.at`