Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 56 additions & 3 deletions crates/gaviero-remote/PROTOCOL.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Gaviero Remote Protocol — v1.9 (1.0 frozen; 1.1 through 1.9 additive)
# Gaviero Remote Protocol — v1.10 (1.0 frozen; 1.1 through 1.10 additive)

Normative wire contract between the gaviero TUI sidecar (server) and the mobile client.
1.0 was frozen by Plan A V3 unit A0 on 2026-08-05; 1.1 was added by Plan C V1 unit C0 on
Expand All @@ -8,7 +8,7 @@ truth); one example fixture per frame lives in [`fixtures/`](fixtures/). Where p
schema disagree, the schema wins.

```
PROTOCOL_VERSION = { major: 1, minor: 9 }
PROTOCOL_VERSION = { major: 1, minor: 10 }
WebSocket path = /v1/ws
Subprotocol = gaviero.v1
Instances path = /v1/instances (HTTPS GET, 1.1, on every instance)
Expand Down Expand Up @@ -182,6 +182,7 @@ holds the current token.
| `read_file` | `{ path }` — requires `file_browser`; reads one regular UTF-8 file, read-only. |
| `turn_review_action` | `{ turn_id, action, path?, folder? }` — requires `turn_review` (1.2); see §1.2 additions; `folder` since 1.5 (§Turn review folders) |
| `request_skill_completions` | `{ query, limit? }` — requires `skill_completions` (1.8); catalog skills for a `$skill` invocation |
| `request_swarm` | `{ agent_id?, output_token? }` — requires `swarm_activity` (1.10); the desktop SWARM panel's run and one agent's output, read-only |

There is **no** `rotate_token` command. Rotation is desktop-only and reaches the client as
close 4006.
Expand Down Expand Up @@ -220,7 +221,7 @@ share a folder name, each gains the nearest parent folder that tells them apart

`hello.capabilities` is an array of strings, **empty in 1.0**; the shape is frozen so
minor versions can advertise features. 1.1 advertises `latest_page` and `instances`; 1.2 adds
`turn_review`; 1.3 adds `file_browser`; 1.4 adds `permission_turn_grant`; 1.6 adds `permission_grants`; 1.7 adds `shell_history`; 1.8 adds `skill_completions`. Clients
`turn_review`; 1.3 adds `file_browser`; 1.4 adds `permission_turn_grant`; 1.6 adds `permission_grants`; 1.7 adds `shell_history`; 1.8 adds `skill_completions`; 1.10 adds `swarm_activity`. Clients
ignore unknown entries.

## DTOs
Expand Down Expand Up @@ -485,6 +486,58 @@ and is not escaped, with at least two characters typed and no space between it
and the caret — and on tap replaces the token with `insert` plus a space.
Older servers receive no skill completion requests.

## Swarm activity (`swarm_activity` capability, 1.10)

Servers advertising `swarm_activity` answer `request_swarm` with what the desktop SWARM panel
(`Alt+w`) shows for its run: the header, one row per agent, and one agent's output. The desktop
runs one script at a time, so there is at most one run; after it ends it stays readable until the
next one starts. The view is read-only — there is no start, stop or undo command.

`request_swarm`: `{ "agent_id": "scout", "output_token": "3:17" }`, both optional. `agent_id`
picks whose output to return; absent, or not in the run, ⇒ the agent selected on the desktop
(which follows the agent that started last until the user picks one). The phone's choice never
moves the desktop selection. `output_token` is the `output.token` of the previous reply.

The completed `command_result.result`:

```json
{ "run": { "run_id": 3, "script": "deep_explore", "phase": "running", "running": true,
"tier_current": 1, "tier_total": 3, "cost_usd": 0.042, "message": "",
"counts": { "running": 1, "queued": 1, "done": 0, "failed": 0 },
"agents": [ { "id": "scout", "status": "running", "error": null,
"detail": "[Read src/main.rs]", "tier": "cheap",
"backend": "claude:haiku", "elapsed_ms": 12000,
"branch": null, "modified_files": [] } ] },
"selected_id": "scout",
"output": { "agent_id": "scout", "token": "3:17", "unchanged": false,
"lines": [ { "kind": "status", "text": "Running: reading" },
{ "kind": "text", "text": "Looking at the entry point…" },
{ "kind": "tool_call", "text": "[Read src/main.rs]" } ],
"truncated": false } }
```

No run since the desktop started ⇒ `{ "run": null, "selected_id": null, "output": null }`.

- `phase` is the desktop's display string (`starting`, a pipeline phase, `completed`,
`completed with failures`, `failed`, `stopped`, `reverted`). `message` is the run-wide note the
desktop shows under the header (preparation notes, the failure, gate results); may be empty.
- `status ∈ queued | running | completed | failed`; `error` is the reason when `failed`
(`not run`, `stopped`, … for agents a run never finished). `tier ∈ cheap | expensive | null`;
`backend` is the `provider:model` it was dispatched to, once known. `elapsed_ms` is the run time
at reply time (frozen once the agent finished; null before it started) — clients may tick it
locally for running agents between polls. `branch` and `modified_files` come from the agent's
manifest when the run completes.
- `output.lines` are the agent's activity, oldest first: `text` (streamed answer, ANSI stripped;
may contain newlines), `tool_call`, `status` (state changes), `file_change` (`[wrote path +a -d]`).
At most the newest 64 KiB; `truncated: true` when older output was left out (the desktop itself
keeps 500 lines / 256 KiB per agent).
- `output.token` changes whenever that agent's output changes (and with every new run). When the
request's `output_token` equals it, `output` is `{ agent_id, token, unchanged: true }` with no
`lines` — keep what you have. The header and agents are always sent in full.

The Flutter client polls it about once a second while its Swarm section is on screen. Older
servers receive no swarm requests.

## File browser (`file_browser` capability)

Servers advertising `hello.capabilities: ["file_browser", ...]` implement the read-only workspace
Expand Down
13 changes: 13 additions & 0 deletions crates/gaviero-remote/fixtures/client/request_swarm.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
{
"version": {
"major": 1,
"minor": 10
},
"instance_id": "a3f9c2e14b7d8650",
"command_id": "cmd-request_swarm",
"type": "request_swarm",
"payload": {
"agent_id": "scout",
"output_token": "3:17"
}
}
45 changes: 41 additions & 4 deletions crates/gaviero-remote/protocol.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@
]
},
"ProtocolVersion": {
"description": "Wire protocol version. Deliberately unrelated to any plan-document\nversion: this is the first protocol ever on the wire, so it starts at\nmajor 1 (Plan A V3 §0.1 item 1). Minor 1 (Plan C V1 §4) is additive:\n`hello.machine`, capability strings, optional\n`request_messages.before_seq`, and the `GET /v1/instances` resource.\nMinor 2 is additive: the turn-review frames, `snapshot.open_turn_reviews`,\nand two error codes. Minor 3 is additive: the `file_browser` capability\nwith the `list_directory` / `read_file` client frames. Minor 4 is\nadditive: the `permission_turn_grant` capability, optional\n`permission_request.mcp_server` and `permission_decision.grant`. Minor 5\nis additive: optional `TurnReviewFile.folder` and\n`turn_review_action.folder` (no capability — a client groups by `folder`\nwhen files carry it, and echoes it only then). Minor 6 is additive: the\n`permission_grants` capability, optional `permission_request.grants`, and\nthree more `PermissionGrant` values (`tool_session`,\n`mcp_server_session`, `turn_all`) — the desktop's `a` / `A` / `p` keys.\nMinor 7 is additive: the `shell_history` capability and optional\n`request_terminals.history`. Minor 8 is additive: the `skill_completions`\ncapability and the `request_skill_completions` client frame. Minor 9 is\nadditive: optional `InstanceInfo.last_activity_at` in `GET /v1/instances`.",
"description": "Wire protocol version. Deliberately unrelated to any plan-document\nversion: this is the first protocol ever on the wire, so it starts at\nmajor 1 (Plan A V3 §0.1 item 1). Minor 1 (Plan C V1 §4) is additive:\n`hello.machine`, capability strings, optional\n`request_messages.before_seq`, and the `GET /v1/instances` resource.\nMinor 2 is additive: the turn-review frames, `snapshot.open_turn_reviews`,\nand two error codes. Minor 3 is additive: the `file_browser` capability\nwith the `list_directory` / `read_file` client frames. Minor 4 is\nadditive: the `permission_turn_grant` capability, optional\n`permission_request.mcp_server` and `permission_decision.grant`. Minor 5\nis additive: optional `TurnReviewFile.folder` and\n`turn_review_action.folder` (no capability — a client groups by `folder`\nwhen files carry it, and echoes it only then). Minor 6 is additive: the\n`permission_grants` capability, optional `permission_request.grants`, and\nthree more `PermissionGrant` values (`tool_session`,\n`mcp_server_session`, `turn_all`) — the desktop's `a` / `A` / `p` keys.\nMinor 7 is additive: the `shell_history` capability and optional\n`request_terminals.history`. Minor 8 is additive: the `skill_completions`\ncapability and the `request_skill_completions` client frame. Minor 9 is\nadditive: optional `InstanceInfo.last_activity_at` in `GET /v1/instances`.\nMinor 10 is additive: the `swarm_activity` capability and the\n`request_swarm` client frame.",
"properties": {
"major": {
"format": "uint16",
Expand Down Expand Up @@ -260,6 +260,26 @@
],
"type": "object"
},
"RequestSwarm": {
"description": "Read the SWARM panel's run (1.10, `swarm_activity`). Polled; never moves\nthe desktop's selection.",
"properties": {
"agent_id": {
"description": "Agent whose output to return. Absent, or no longer in the run ⇒ the\nagent selected on the desktop.",
"type": [
"string",
"null"
]
},
"output_token": {
"description": "`output.token` from the previous reply. When the chosen agent's output\nhas not changed since, the reply carries `output.unchanged: true` and\nno lines.",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"RequestTerminals": {
"properties": {
"history": {
Expand Down Expand Up @@ -771,6 +791,23 @@
"payload"
],
"type": "object"
},
{
"description": "1.10 (`swarm_activity`): the SWARM panel's run and one agent's output.",
"properties": {
"payload": {
"$ref": "#/$defs/RequestSwarm"
},
"type": {
"const": "request_swarm",
"type": "string"
}
},
"required": [
"type",
"payload"
],
"type": "object"
}
],
"properties": {
Expand Down Expand Up @@ -848,7 +885,7 @@
"type": "object"
},
"ProtocolVersion": {
"description": "Wire protocol version. Deliberately unrelated to any plan-document\nversion: this is the first protocol ever on the wire, so it starts at\nmajor 1 (Plan A V3 §0.1 item 1). Minor 1 (Plan C V1 §4) is additive:\n`hello.machine`, capability strings, optional\n`request_messages.before_seq`, and the `GET /v1/instances` resource.\nMinor 2 is additive: the turn-review frames, `snapshot.open_turn_reviews`,\nand two error codes. Minor 3 is additive: the `file_browser` capability\nwith the `list_directory` / `read_file` client frames. Minor 4 is\nadditive: the `permission_turn_grant` capability, optional\n`permission_request.mcp_server` and `permission_decision.grant`. Minor 5\nis additive: optional `TurnReviewFile.folder` and\n`turn_review_action.folder` (no capability — a client groups by `folder`\nwhen files carry it, and echoes it only then). Minor 6 is additive: the\n`permission_grants` capability, optional `permission_request.grants`, and\nthree more `PermissionGrant` values (`tool_session`,\n`mcp_server_session`, `turn_all`) — the desktop's `a` / `A` / `p` keys.\nMinor 7 is additive: the `shell_history` capability and optional\n`request_terminals.history`. Minor 8 is additive: the `skill_completions`\ncapability and the `request_skill_completions` client frame. Minor 9 is\nadditive: optional `InstanceInfo.last_activity_at` in `GET /v1/instances`.",
"description": "Wire protocol version. Deliberately unrelated to any plan-document\nversion: this is the first protocol ever on the wire, so it starts at\nmajor 1 (Plan A V3 §0.1 item 1). Minor 1 (Plan C V1 §4) is additive:\n`hello.machine`, capability strings, optional\n`request_messages.before_seq`, and the `GET /v1/instances` resource.\nMinor 2 is additive: the turn-review frames, `snapshot.open_turn_reviews`,\nand two error codes. Minor 3 is additive: the `file_browser` capability\nwith the `list_directory` / `read_file` client frames. Minor 4 is\nadditive: the `permission_turn_grant` capability, optional\n`permission_request.mcp_server` and `permission_decision.grant`. Minor 5\nis additive: optional `TurnReviewFile.folder` and\n`turn_review_action.folder` (no capability — a client groups by `folder`\nwhen files carry it, and echoes it only then). Minor 6 is additive: the\n`permission_grants` capability, optional `permission_request.grants`, and\nthree more `PermissionGrant` values (`tool_session`,\n`mcp_server_session`, `turn_all`) — the desktop's `a` / `A` / `p` keys.\nMinor 7 is additive: the `shell_history` capability and optional\n`request_terminals.history`. Minor 8 is additive: the `skill_completions`\ncapability and the `request_skill_completions` client frame. Minor 9 is\nadditive: optional `InstanceInfo.last_activity_at` in `GET /v1/instances`.\nMinor 10 is additive: the `swarm_activity` capability and the\n`request_swarm` client frame.",
"properties": {
"major": {
"format": "uint16",
Expand Down Expand Up @@ -919,7 +956,7 @@
"instances_path": "/v1/instances",
"protocol_version": {
"major": 1,
"minor": 9
"minor": 10
},
"server_envelope": {
"$defs": {
Expand Down Expand Up @@ -1865,7 +1902,7 @@
"type": "object"
},
"ProtocolVersion": {
"description": "Wire protocol version. Deliberately unrelated to any plan-document\nversion: this is the first protocol ever on the wire, so it starts at\nmajor 1 (Plan A V3 §0.1 item 1). Minor 1 (Plan C V1 §4) is additive:\n`hello.machine`, capability strings, optional\n`request_messages.before_seq`, and the `GET /v1/instances` resource.\nMinor 2 is additive: the turn-review frames, `snapshot.open_turn_reviews`,\nand two error codes. Minor 3 is additive: the `file_browser` capability\nwith the `list_directory` / `read_file` client frames. Minor 4 is\nadditive: the `permission_turn_grant` capability, optional\n`permission_request.mcp_server` and `permission_decision.grant`. Minor 5\nis additive: optional `TurnReviewFile.folder` and\n`turn_review_action.folder` (no capability — a client groups by `folder`\nwhen files carry it, and echoes it only then). Minor 6 is additive: the\n`permission_grants` capability, optional `permission_request.grants`, and\nthree more `PermissionGrant` values (`tool_session`,\n`mcp_server_session`, `turn_all`) — the desktop's `a` / `A` / `p` keys.\nMinor 7 is additive: the `shell_history` capability and optional\n`request_terminals.history`. Minor 8 is additive: the `skill_completions`\ncapability and the `request_skill_completions` client frame. Minor 9 is\nadditive: optional `InstanceInfo.last_activity_at` in `GET /v1/instances`.",
"description": "Wire protocol version. Deliberately unrelated to any plan-document\nversion: this is the first protocol ever on the wire, so it starts at\nmajor 1 (Plan A V3 §0.1 item 1). Minor 1 (Plan C V1 §4) is additive:\n`hello.machine`, capability strings, optional\n`request_messages.before_seq`, and the `GET /v1/instances` resource.\nMinor 2 is additive: the turn-review frames, `snapshot.open_turn_reviews`,\nand two error codes. Minor 3 is additive: the `file_browser` capability\nwith the `list_directory` / `read_file` client frames. Minor 4 is\nadditive: the `permission_turn_grant` capability, optional\n`permission_request.mcp_server` and `permission_decision.grant`. Minor 5\nis additive: optional `TurnReviewFile.folder` and\n`turn_review_action.folder` (no capability — a client groups by `folder`\nwhen files carry it, and echoes it only then). Minor 6 is additive: the\n`permission_grants` capability, optional `permission_request.grants`, and\nthree more `PermissionGrant` values (`tool_session`,\n`mcp_server_session`, `turn_all`) — the desktop's `a` / `A` / `p` keys.\nMinor 7 is additive: the `shell_history` capability and optional\n`request_terminals.history`. Minor 8 is additive: the `skill_completions`\ncapability and the `request_skill_completions` client frame. Minor 9 is\nadditive: optional `InstanceInfo.last_activity_at` in `GET /v1/instances`.\nMinor 10 is additive: the `swarm_activity` capability and the\n`request_swarm` client frame.",
"properties": {
"major": {
"format": "uint16",
Expand Down
18 changes: 18 additions & 0 deletions crates/gaviero-remote/src/envelope.rs
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,8 @@ pub enum ClientFrame {
TurnReviewAction(TurnReviewAction),
/// 1.8 (`skill_completions`): catalog skills for a `$skill` invocation.
RequestSkillCompletions(RequestSkillCompletions),
/// 1.10 (`swarm_activity`): the SWARM panel's run and one agent's output.
RequestSwarm(RequestSwarm),
}

impl ClientFrame {
Expand All @@ -64,6 +66,7 @@ impl ClientFrame {
"read_file",
"turn_review_action",
"request_skill_completions",
"request_swarm",
];
}

Expand Down Expand Up @@ -206,6 +209,21 @@ pub struct RequestSkillCompletions {
pub limit: Option<u32>,
}

/// Read the SWARM panel's run (1.10, `swarm_activity`). Polled; never moves
/// the desktop's selection.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct RequestSwarm {
/// Agent whose output to return. Absent, or no longer in the run ⇒ the
/// agent selected on the desktop.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub agent_id: Option<String>,
/// `output.token` from the previous reply. When the chosen agent's output
/// has not changed since, the reply carries `output.unchanged: true` and
/// no lines.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub output_token: Option<String>,
}

#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct ListDirectory {
/// Explorer display path (`<root-label>/<rel>`). Omitted or empty lists
Expand Down
9 changes: 7 additions & 2 deletions crates/gaviero-remote/src/version.rs
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,15 @@ use serde::{Deserialize, Serialize};
/// `request_terminals.history`. Minor 8 is additive: the `skill_completions`
/// capability and the `request_skill_completions` client frame. Minor 9 is
/// additive: optional `InstanceInfo.last_activity_at` in `GET /v1/instances`.
/// Minor 10 is additive: the `swarm_activity` capability and the
/// `request_swarm` client frame.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ProtocolVersion {
pub major: u16,
pub minor: u16,
}

pub const PROTOCOL_VERSION: ProtocolVersion = ProtocolVersion { major: 1, minor: 9 };
pub const PROTOCOL_VERSION: ProtocolVersion = ProtocolVersion { major: 1, minor: 10 };

/// `hello.capabilities` entries this server version advertises (Plan C §4.1).
pub mod capability {
Expand All @@ -53,6 +55,9 @@ pub mod capability {
/// 1.8: `request_skill_completions` lists catalog skills for a `$skill`
/// invocation.
pub const SKILL_COMPLETIONS: &str = "skill_completions";
/// 1.10: `request_swarm` reads the SWARM panel's run — its agents, their
/// state, and one agent's output. Read-only.
pub const SWARM_ACTIVITY: &str = "swarm_activity";
}

/// Why a peer's version is unacceptable.
Expand Down Expand Up @@ -90,7 +95,7 @@ mod tests {
.is_ok()
);
assert!(
ours.check_compatible(&ProtocolVersion { major: 1, minor: 9 })
ours.check_compatible(&ProtocolVersion { major: 1, minor: 10 })
.is_ok()
);
}
Expand Down
Loading
Loading