# Dialup Agent API

## About Dialup

Dialup is an open-source Elixir web framework ([GitHub](https://github.com/SouichiroTsujimoto/Dialup), [HexDocs](https://hexdocs.pm/dialup)).
Each page declares UI with `<.dialup_action>` and `<.dialup_region>`; the framework derives MCP-compatible HTTP tools (`initialize`, `tools/list`, `tools/call`, `read_scene`) from those declarations — no separate REST API to maintain.

`https://dialup-framework.org` runs Dialup. This `/agent` document is generated by the framework itself (the same mechanism Dialup apps expose to chat agents).

```
Human browser ──WebSocket──► UserSessionProcess ◄──HTTP JSON-RPC── Chat agent
                                    │
                             same state / events
```

## Readable endpoints (GET)

Plain-text GET resources (no authentication):

- `GET https://dialup-framework.org/agent` — this document
- `GET https://dialup-framework.org/llms.txt` — full agent protocol and session-bearer reference
- `GET https://dialup-framework.org/.well-known/dialup-agent?path=<page-path>` — tool catalog for a page path

## HTTP API (POST)

- **Request:** `POST https://dialup-framework.org/agent`
- **Headers:** `Content-Type: application/json`, `Authorization: Bearer <bootstrap or session bearer>`
- **Body:** JSON-RPC 2.0 — methods include `initialize`, `tools/list`, `tools/call`

## Bootstrap exchange

Opening **AI に渡す** in the live browser tab issues two copyable lines:

```
https://dialup-framework.org/agent
Authorization: Bearer <bootstrap>
```

The bootstrap bearer lists only `rotate_agent_token` in tools/list.
A successful `tools/call rotate_agent_token` revokes the bootstrap bearer and returns a session bearer with the page's normal grant.

Each time **AI に渡す** is opened, a fresh bootstrap bearer is issued.

## Design notes

- Page navigation and mutations are declared JSON-RPC tools on the live session (`navigate_*`, etc.), not ad-hoc GETs to HTML routes.
- The WebSocket UI and the HTTP JSON-RPC client share one server-side `UserSessionProcess`; accepted `tools/call` mirrors to the browser tab.
- IDE MCP server registration is a separate integration path from this chat handoff flow.
- Browser automation (Playwright, Puppeteer, etc.) attaches to a different session than the person's open tab.

## Connect sequence (reference)

1. A person uses the app in a browser (WebSocket live).
2. They open **AI に渡す** and copy these two lines into chat (optionally with a task):

   ```
   https://dialup-framework.org/agent
   Authorization: Bearer <bootstrap>
   ```

3. `POST https://dialup-framework.org/agent` with bootstrap bearer → JSON-RPC (`initialize`, `tools/list`, `tools/call rotate_agent_token`).
4. `rotate_agent_token` returns a session bearer; the bootstrap bearer is revoked.
5. Further `POST https://dialup-framework.org/agent` calls use the session bearer; operations mirror to the open tab.

## Endpoints

- `GET /agent` — chat entry document (optional; bearer is sufficient for POST)
- `POST /agent` — JSON-RPC (`initialize`, `tools/list`, `tools/call`)
- `/.well-known/dialup-agent?path=...` — tool catalog for a page path

## Versioning and expiry

- Human UI uses WebSocket (`/ws`); agent tools use HTTP request-response.
- Actions with `confirm=human` require the browser UI.
- Mutating tools expect `_version` from the latest `read_scene`.
- Expired bootstrap or session bearers: open **AI に渡す** again for a fresh bootstrap bearer.