# Connecting your own agent to Grix over ACP

This guide is for developers who have an agent that speaks the
[Agent Client Protocol](https://agentclientprotocol.com) (ACP) over stdio
JSON-RPC and want it to appear in Grix as a chat participant — no Grix code
change, no Grix release.

It covers the whole surface: how to connect, how your output reaches the user,
how to ask the user a question and get the answer back, what the toolbar can
show, and how to render rich cards. Every claim below is the behavior of the
code in this repository at the time of writing; where something is *not*
supported, this guide says so instead of leaving you to discover it.

---

## 1. Connect

Add one entry to the grix-connector agent config and restart the connector.

```json
{
  "name": "my-acp-agent",
  "ws_url": "wss://ws.grix.im/v1/agent-api/ws",
  "agent_id": "<agent-id from the Grix app>",
  "api_key": "<api key from the Grix app>",
  "client_type": "acp",
  "command": "my-agent",
  "args": ["--acp"],
  "cwd": "/srv/my-agent"
}
```

| Field | Required | Meaning |
| --- | --- | --- |
| `client_type` | yes | Must be `"acp"`. This is the vendor-neutral type; it is what makes the rest of this guide apply. |
| `command` | yes | The executable the connector spawns. Nothing is injected for you. |
| `args` | no | Passed verbatim. Put whatever flag starts your ACP mode here. |
| `cwd` | no | The fixed working directory. See below. |
| `env` | no | Extra environment for the spawned process. |
| `acp_new_session_params` | no | Extra fields merged into your `session/new` params, for arguments the protocol does not define. |

### Working directory

ACP's `session/new` requires an absolute `cwd`, but Grix never asks the owner
to pick one for a generic ACP agent. The connector supplies it from `cwd` in
the config, falling back to the home directory. It is fixed:

- `/grix open` and `/grix unbind` are rejected in chat.
- The toolbar has no binding entry.
- To move the agent, edit `cwd` and restart the connector.
- A `cwd` that does not exist is logged as an error and falls back to the home
  directory, so a typo cannot strand the agent.

Every chat session still gets its own ACP session (its own `session/new`); they
simply all share the same directory.

### What you get without writing anything

- **Grix MCP server**, injected into your `session/new` `mcpServers` list. Your
  agent can call the Grix platform directly — see §6.
- **Skills**: discovery falls back to the Gemini layout, so the connector reads
  `~/.gemini/skills`. This is deliberate and will not be changed; an agent that
  needs its own skill directory has to be registered as its own `client_type`.
- **Streaming**: your `session/update` text chunks are forwarded incrementally
  and the client shows them as they arrive.
- **Stop**: the toolbar's stop button calls ACP `session/cancel`.

---

## 2. Talking to the user

Plain agent output is the normal path. Emit `session/update` notifications with
`agent_message_chunk` and the text appears in the chat, streamed.

A user message arrives as an ACP `session/prompt` call. That is the whole
request/response loop; you do not implement any Grix protocol.

---

## 3. Asking the user a question

**This is the part most people look for, so read it carefully: you ask a
question through ACP's permission channel, not through a Grix API.**

Send `session/request_permission` shaped as a question and the connector turns
it into a tappable choice card in chat. The user's tap comes back as the return
value of that same `session/request_permission` call — your turn simply resumes.

The connector recognizes a permission request as a question when **all** of the
following hold:

1. The tool name or tool title, lowercased with non-letters stripped, contains
   `askuserquestion`. In practice: name your tool `AskUserQuestion`.
2. `toolCall.content` carries non-empty text. This becomes the prompt shown to
   the user.
3. At least one option has a `kind` **outside** the standard permission
   vocabulary `allow_once`, `allow_always`, `reject_once`, `reject_always`.
   A request whose options are entirely standard kinds is treated as an
   ordinary permission gate (§4), not a question — two options alone do not
   distinguish them, since `allow_once` + `reject_once` is also two options.

```jsonc
// session/request_permission params
{
  "sessionId": "...",
  "toolCall": {
    "toolCallId": "q-1",
    "title": "AskUserQuestion",
    "content": [{ "type": "content", "content": { "type": "text", "text": "Which environment should I deploy to?" } }]
  },
  "options": [
    { "optionId": "staging",    "name": "Staging",    "kind": "answer" },
    { "optionId": "production", "name": "Production", "kind": "answer" }
  ]
}
```

The user sees a card with "Staging" and "Production". Tapping one resolves the
call with that `optionId`.

Notes that will save you time:

- **Free text depends on a dismissal option.** When the request carries a
  kimi-style `q{n}_skip` option, the card declares `allow_free_text` and shows
  a text input; an answer matching no option dismisses the question via that
  skip option and is then delivered to the agent as a follow-up
  `session/prompt`. Without a `q{n}_skip` option the answer has to match one
  of your options by `name` or `optionId`; anything else is rejected with
  *"please tap one of the options on the card"* and the question stays open.
- An option whose `optionId` ends in `_skip`, or whose `kind` contains
  `reject`, is treated as the cancel path rather than an answer.
- The question does not pause the idle watchdog. If nobody answers, the turn
  fails after the 15-minute inactivity cap rather than hanging forever.
- One question at a time per request id; the card is resolved once.

---

## 4. Permission gates

An ordinary `session/request_permission` — options drawn from `allow_once`,
`allow_always`, `reject_once`, `reject_always` — renders as an approval card
showing the tool name and its input. Approve/reject comes back as the return
value of your call. Nothing to implement.

If the agent is configured in `yolo` or `autoEdit` approval mode, the connector
auto-approves and never shows a card — including for question-shaped requests,
because those modes mean "never stop for an interactive prompt".

---

## 5. The toolbar

The toolbar is the row of controls above the chat input. For `client_type:
"acp"` it is deliberately minimal, and **it is empty — and therefore hidden —
while the agent is idle.**

What can appear:

| Control | Where it comes from | What the user's choice does |
| --- | --- | --- |
| Stop | Shown while a turn is running | ACP `session/cancel` |
| Mode selector | The `modes` your `session/new` response reports | ACP `session/set_mode` with the chosen mode id |
| Model selector | The `models` your `session/new` response reports | ACP `session/set_model` with the chosen model id |
| Skills | Skills discovered on disk | Skill enable/disable |
| Browse files, queue | Added automatically whenever the toolbar is visible | Handled by the connector |

**So the toolbar already supports one kind of multiple-choice control, and it
costs you nothing:** report `modes` and/or `models` in your `session/new`
response and implement `session/set_mode` / `session/set_model`. The
selector renders itself, remembers the current value, and calls you back. If
you report neither, no selector is rendered — Grix will not hang a control on
your agent that it cannot honor.

### Your own toolbar controls

Beyond modes and models you can declare **your own** controls with the
`grix_toolbar_set` MCP tool (§6). Two kinds, deliberately:

```jsonc
grix_toolbar_set({
  items: [
    { id: "env", kind: "select", label: "Environment",
      value: "staging",
      options: [ {id: "staging", label: "Staging"}, {id: "prod", label: "Production"} ] },
    { id: "howto", kind: "info", label: "How to use",
      info_title: "Deploy flow",
      info_text: "Pick an environment, then just say \"deploy\" — I run a dry-run first." }
  ]
})
```

- **`select`** renders a dropdown. When the user picks an option, you receive a
  message whose content is exactly
  `grix://toolbar/select?item=<item id>&option=<option id>` — an ordinary
  `session/prompt` turn, so your reply streams back into the chat as usual.
  It is delivered only while you are idle (see the limits below), and it does
  **not** appear in the chat as a user message.
- **`info`** renders a button that shows `info_text` in a dialog when tapped.
  It is entirely client-side: nothing is sent anywhere, and you never hear
  about the tap. Use it for a usage hint or a legend.

Call `grix_toolbar_set` again with the full desired list to change the toolbar,
or with `items: []` to remove your controls. The declaration is per chat
session, and the tool defaults `session_id` to the session your ACP session is
bound to.

**Limits, all enforced. A payload that breaks any of them is rejected whole —
you will not get a half-rendered toolbar:**

| Rule | Limit |
| --- | --- |
| Items per session | 6 |
| `id` (items and options) | `[a-z0-9_]+`, max 32 chars, unique |
| `label` | 1–20 characters |
| Options per `select` | 1–20 |
| Option `label` | 1–40 characters |
| `info_text` | 1–500 characters, plain text |
| `value` | must be one of that item's option ids |

Two more behaviors worth knowing:

- Your ids are namespaced (`env` becomes `custom_env`), so you cannot collide
  with or displace a built-in control such as stop.
- A `select` is **disabled while a turn is running**, because an ACP session
  runs one turn at a time. Choices arrive between turns.

Anything beyond a dropdown and an info button — free text input, a button that
runs an action, a progress bar — is not available. Ask through a question card
(§3) instead.

## 6. Calling the Grix platform from your agent

The connector injects a Grix MCP server into your ACP session by default, so
your agent sees these as ordinary MCP tools. The ones you are most likely to
want:

| Tool | Use |
| --- | --- |
| `grix_message_send` | Send a message into any session the owner can see (max 10 000 chars). |
| `grix_reply` | Send the final answer to the session you are handling (max 50 000 chars). |
| `grix_session_send` | Speak as the owner in a session. |
| `grix_file_upload` / `grix_file_link` | Hand the user a file, as an attachment or a link. |
| `grix_query` | Look up contacts, sessions, message history. |
| `grix_call_owner` | Pull the owner into the session for a voice talk or approval. |
| `grix_dispatch_agent` | Hand work to one of the owner's other agents. |
| `grix_composing` | Show the typing indicator during long work. |
| `grix_toolbar_set` | Declare your own toolbar controls (§5). `client_type: "acp"` only; other client types are rejected with an explicit error rather than silently ignored. |
| `grix_webhook_create` / `grix_webhook_list` / `grix_webhook_delete` | Give yourself a standing HTTP trigger. |

Do not use `grix_message_send` to answer the message you are currently
handling — answer through your normal ACP output, or the user gets the reply
twice.

Set `"acp_mcp_tools": false` in `adapterOptions` if you want the session
without them.

---

## 7. Cards

Cards are the rich message blocks in the Grix client — approval prompts,
question forms, status blocks. The wire format is a markdown link whose target
is a `grix://card/` URI:

```
[fallback text](grix://card/{type}?d={url-encoded json payload})
```

The client parses this **strictly and only when the whole message is exactly
that one link** — no surrounding prose, no second paragraph. If it does not
match, the user sees the raw text. So send a card as its own message, most
easily with `grix_message_send`.

Types the client renders: `agent_question`, `agent_status`, `agent_pairing`,
`exec_approval`, `exec_status`, `tool_execution`, `tool_execution_group`,
`user_profile`, `conversation`, `egg_install_status`, `call_owner`, `thinking`,
`progress`, `agent_open_session`.

`agent_status` is the useful one to hand-build — a titled status block with no
interaction:

```jsonc
// grix_message_send content:
// [Deploy](grix://card/agent_status?d=<urlencoded>)
{
  "category": "deploy",              // required
  "status": "success",               // required; success | warning | error style the card, anything else renders neutral
  "summary": "Deployed to staging",  // required
  "detail_text": "7 services updated"
}
```

### Hand-built cards are display-only

Emit whichever of those types you like — but only the non-interactive ones
actually work end to end. `agent_question` renders if you build it by hand, yet
its answer will not reach you: the reply comes back carrying your `request_id`,
and the connector only honours a `request_id` it issued itself from a
`session/request_permission`. A hand-built id is unknown to it, so the user
gets *"The question is no longer pending"* and your agent hears nothing.

This is by design — interaction has exactly one supported route so there is
only one thing to get right. **Ask through §3, offer standing choices through
the toolbar (§5), and keep hand-built cards to display types like
`agent_status`.**

---

## 8. Limits of the generic entry

These are deliberate. An agent that needs any of them must be registered as its
own `client_type`, which is a Grix code change and release:

- Its own skill directory (the generic entry shares `~/.gemini/skills`).
- Session usage / token accounting (`get_session_usage` is not declared —
  there is no parser for an unknown CLI's usage output).
- A quota card, context-window readout, or built-in slash command list. (A
  toolbar you control yourself is available — see §5 — but a *branded* toolbar
  with bespoke controls is not.)
- A branded installation guide in the app.
- Session history scanning (the session list button is not offered, because
  scanning needs a known CLI's on-disk history layout).

---

## 9. Checklist

- [ ] Agent speaks ACP over stdio JSON-RPC and implements `session/new`,
      `session/prompt`, `session/cancel`.
- [ ] Config entry added with `client_type: "acp"`, `command`, and a `cwd` that
      exists.
- [ ] `session/new` reports `modes` / `models` if you want toolbar selectors,
      with `session/set_mode` / `session/set_model` implemented.
- [ ] Your own toolbar controls, if any, declared with `grix_toolbar_set`, and
      `grix://toolbar/select?...` prompts handled.
- [ ] Questions asked through `session/request_permission` with an
      `AskUserQuestion`-named tool, non-empty `toolCall.content`, and at least
      one option with a non-standard `kind`.
- [ ] Nothing depends on the owner choosing a working directory.
