Tairitsu Debug Agent Skill

Protocol version: 0.1.0 | Base URL: http://localhost:<debug-port> (default: dev-port + 1)

Overview

When tairitsu dev is launched with --debug, the packager exposes a Debug API server on a dedicated port (default: 3001 when dev server is on 3000). Agents connect via HTTP to perform browser automation — screenshots, DOM inspection, click/input simulation, JS evaluation — without needing a separate Playwright or Puppeteer process.

Startup

# Start dev server with debug API enabled
just dev --daemon --debug

# Custom debug port
just dev --daemon --debug --debug-port 9223

The debug server starts alongside the dev server. Check readiness:

curl -s http://localhost:3001/health | jq .

Expected response:

{
  "ok": true,
  "data": {
    "status": "ok",
    "version": "0.1.0",
    "api_version": "0.1.0",
    "uptime_secs": 42
  }
}

Endpoints

All endpoints return {"ok": bool, "data"?: ..., "error"?: string}. All POST bodies are JSON. All responses are JSON.

`GET /health`

Liveness check. Always returns 200 if the debug server is running.

`GET /info`

Server metadata: version, ports, dist dir, package name, PID, uptime, browser status.

`POST /navigate`

Navigate the managed browser context to a URL.

{
  "url": "/button"
}

Relative URLs are resolved against the dev server base (http://localhost:<dev_port>).

Response: { "url": "...", "title": "..." }

`POST /screenshot`

Capture a screenshot of the current page (or an element).

{
  "selector": "#hikari-app",
  "full_page": false,
  "format": "png"
}

Field	Type	Default	Description
`selector`	string?	`null`	CSS selector to screenshot. `null` = full viewport
`full_page`	bool?	`false`	Capture full scrollable page
`format`	string?	`"png"`	Image format (`png`, `jpeg`)

Response: { "data": "<base64-encoded image>", "mime_type": "image/png", "width": 1920, "height": 1080 }

`POST /click`

Click an element matching a CSS selector.

{
  "selector": "#my-button",
  "button": "left",
  "modifiers": []
}

Field	Type	Default	Description
`selector`	string	(required)	CSS selector
`button`	string?	`"left"`	Mouse button
`modifiers`	string[]?	`[]`	Key modifiers (`Shift`, `Control`, `Alt`)

Response: { "ok": true } or error if element not found.

`POST /type`

Type text into an input element.

{
  "selector": "input[name='search']",
  "text": "hello world",
  "clear_first": true,
  "submit": false
}

Field	Type	Default	Description
`selector`	string	(required)	CSS selector for input/textarea
`text`	string	(required)	Text to type
`clear_first`	bool?	`true`	Clear existing value before typing
`submit`	bool?	`false`	Press Enter after typing

Response: { "ok": true }

`POST /evaluate`

Execute JavaScript in the page context and return the result.

{
  "expression": "document.title",
  "await_promise": false
}

Field	Type	Default	Description
`expression`	string	(required)	JS expression to evaluate
`await_promise`	bool?	`false`	If true, awaits the result as a Promise

Response: { "result": <serialized JS value>, "type": "string|number|boolean|null|object" }

Security note: Evaluation runs in the page context. The debug server binds to 127.0.0.1 only and should never be exposed to networks.

`GET /console`

Retrieve recent console log entries from the managed browser.

Response: { "entries": [{ "level": "log|warn|error", "text": "...", "timestamp": "ISO-8601" }] }

`GET /dom?selector=...&attribute=...`

Query DOM elements by CSS selector.

Query Param	Type	Description
`selector`	string	(required) CSS selector
`attribute`	string?	If set, return only this attribute's value

Response:

{
  "ok": true,
  "data": {
    "tag": "div",
    "text": "Hello World",
    "html": "<div id=\"app\">...</div>",
    "attributes": { "id": "app", "class": "container" },
    "visible": true,
    "count": 1
  }
}

Agent Workflow Example

A typical agent session for visual debugging:

graph TD
    S1["1. GET /health"] --> S2["2. POST /navigate {url: /}"]
    S2 --> S3["3. POST /screenshot {}"]
    S3 --> S4["4. POST /evaluate<br/>(check WASM state)"]
    S4 --> S5["5. POST /click {selector: .btn-primary}"]
    S5 --> S6["6. POST /creenshot {selector: #dialog}"]
    S6 --> S7["7. GET /console"]
    S7 --> S8["8. POST /navigate {url: /switch}"]
    S8 --> S9["9. POST /screenshot {full_page: true}"]

Error Handling

Status Code	Meaning
200	Success
400	Invalid request body or missing parameters
404	Unknown endpoint
503	Browser not connected (headless chromium unavailable)

When ok: false, the error field contains a human-readable description.

Integration Notes

The debug API uses CORS headers, so cross-origin requests from agent runtimes are allowed.
Base URLs in /navigate are relative to the dev server, not the debug server.
Screenshots return base64-encoded PNG/JPEG data — decode before saving or comparing.
Console entries are buffered in-memory and cleared when the server restarts.
Multiple agents can share one debug server; operations are sequential (no locking needed for single-browser use).