# Generated model index

<!-- generated by scripts/generate_api_artifacts.py; do not edit by hand -->

This is a deterministic structural reference derived from public dataclasses.
It is transport-neutral and is not an OpenAPI document. Runtime semantics live
in [../models.md](../models.md). Synthetic examples never read live objects or
stored connection data.

<!-- api-model: AddTagToConnectionsRequest -->
## `AddTagToConnectionsRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Add one tag to multiple connections in one atomic mutation.

**Related methods:** `add_tag_to_connections`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_ids` | `Tuple[ConnectionId, ...]` | Yes | — | No |
| `tag` | `str` | Yes | — | No |
| `expected_generation` | `Optional[int]` | No | `null` | No |

Synthetic representation:

```json
{
  "connection_ids": {},
  "expected_generation": null,
  "tag": {}
}
```

<!-- api-model: AssignConnectionToGroupRequest -->
## `AssignConnectionToGroupRequest`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Move a connection to a group (or root if group_id is empty).

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `group_id` | `str` | No | `` | No |

Synthetic representation:

```json
{
  "connection_id": "production",
  "group_id": ""
}
```

<!-- api-model: AttachSessionRequest -->
## `AttachSessionRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `AttachSessionRequest` record.

**Related methods:** `attach_session`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `session_id` | `SessionId` | Yes | — | No |
| `request_input` | `bool` | No | `true` | No |
| `want_terminal_output` | `bool` | No | `false` | No |
| `from_sequence` | `int` | No | `0` | No |

Synthetic representation:

```json
{
  "from_sequence": 0,
  "request_input": true,
  "session_id": "session-12",
  "want_terminal_output": false
}
```

<!-- api-model: AttachSessionResult -->
## `AttachSessionResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `AttachSessionResult` record.

**Related methods:** `attach_session`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `session` | `SessionSummary` | Yes | — | No |
| `attachment` | `AttachmentInfo` | Yes | — | No |
| `available_start` | `int` | No | `0` | No |
| `live_sequence` | `int` | No | `0` | No |
| `replay_truncated` | `bool` | No | `false` | No |
| `eof` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "attachment": {
    "client_id": "client-abc123",
    "id": "production",
    "input_owner": false,
    "session_id": "session-12"
  },
  "available_start": 0,
  "eof": false,
  "live_sequence": 0,
  "replay_truncated": false,
  "session": {
    "attachment_count": 0,
    "capabilities": {
      "supported": []
    },
    "connection_id": "production",
    "created_at": "<UTC timestamp at creation>",
    "exit_info": null,
    "failure": null,
    "id": "production",
    "input_owner": null,
    "state": "created"
  }
}
```

<!-- api-model: AttachSftpRequest -->
## `AttachSftpRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `AttachSftpRequest` record.

**Related methods:** `attach_sftp`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `service_id` | `SftpServiceId` | Yes | — | No |

Synthetic representation:

```json
{
  "service_id": {}
}
```

<!-- api-model: AttachmentInfo -->
## `AttachmentInfo`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `AttachmentInfo` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `id` | `AttachmentId` | Yes | — | No |
| `session_id` | `SessionId` | Yes | — | No |
| `client_id` | `ClientId` | Yes | — | No |
| `input_owner` | `bool` | Yes | — | No |

Synthetic representation:

```json
{
  "client_id": "client-abc123",
  "id": "production",
  "input_owner": false,
  "session_id": "session-12"
}
```

<!-- api-model: BroadcastTerminalInputRequest -->
## `BroadcastTerminalInputRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Write one command to the existing interactive terminal sessions.

**Related methods:** `broadcast_terminal_input`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `session_ids` | `tuple[SessionId, ...]` | Yes | — | No |
| `command` | `str` | Yes | — | Yes |

Synthetic representation:

```json
{
  "command": "<sensitive value omitted>",
  "session_ids": []
}
```

<!-- api-model: CancelTransferRequest -->
## `CancelTransferRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `CancelTransferRequest` record.

**Related methods:** `cancel_transfer`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `transfer_id` | `TransferId` | Yes | — | No |

Synthetic representation:

```json
{
  "transfer_id": "transfer-3"
}
```

<!-- api-model: Capabilities -->
## `Capabilities`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Capabilities and version information reported by a client.

**Related methods:** `get_capabilities`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `protocol_version` | `str` | Yes | — | No |
| `api_implementation_version` | `str` | Yes | — | No |
| `client` | `ClientInfo` | Yes | — | No |
| `core` | `CoreInfo` | Yes | — | No |
| `supported` | `frozenset[Capability]` | Yes | — | No |
| `compatibility` | `CompatibilityResult` | Yes | — | No |

Synthetic representation:

```json
{
  "api_implementation_version": "example",
  "client": {
    "client_id": null,
    "name": "example",
    "version": "1.0"
  },
  "compatibility": {
    "compatible": false,
    "message": "",
    "protocol_version": "example"
  },
  "core": {
    "implementation": "example",
    "name": "example",
    "version": "1.0"
  },
  "protocol_version": "example",
  "supported": []
}
```

<!-- api-model: ChallengePrompt -->
## `ChallengePrompt`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `ChallengePrompt` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `text` | `str` | Yes | — | No |
| `attempt` | `int` | Yes | — | No |

Synthetic representation:

```json
{
  "attempt": 0,
  "text": "example"
}
```

<!-- api-model: ClaimForwardRequest -->
## `ClaimForwardRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `ClaimForwardRequest` record.

**Related methods:** `claim_forward`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `forward_id` | `ForwardId` | Yes | — | No |

Synthetic representation:

```json
{
  "forward_id": {}
}
```

<!-- api-model: ClaimTerminalInputRequest -->
## `ClaimTerminalInputRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `ClaimTerminalInputRequest` record.

**Related methods:** `claim_terminal_input`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `session_id` | `SessionId` | Yes | — | No |
| `attachment_id` | `AttachmentId` | Yes | — | No |

Synthetic representation:

```json
{
  "attachment_id": "attachment-2",
  "session_id": "session-12"
}
```

<!-- api-model: ClientInfo -->
## `ClientInfo`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Describes the frontend/client implementation.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `name` | `str` | Yes | — | No |
| `version` | `str` | Yes | — | No |
| `client_id` | `ClientId | None` | No | `null` | No |

Synthetic representation:

```json
{
  "client_id": null,
  "name": "example",
  "version": "1.0"
}
```

<!-- api-model: CloseForwardRequest -->
## `CloseForwardRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `CloseForwardRequest` record.

**Related methods:** `close_forward`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `forward_id` | `ForwardId` | Yes | — | No |

Synthetic representation:

```json
{
  "forward_id": {}
}
```

<!-- api-model: CloseSessionRequest -->
## `CloseSessionRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `CloseSessionRequest` record.

**Related methods:** `close_session`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `session_id` | `SessionId` | Yes | — | No |

Synthetic representation:

```json
{
  "session_id": "session-12"
}
```

<!-- api-model: CloseSftpRequest -->
## `CloseSftpRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `CloseSftpRequest` record.

**Related methods:** `close_sftp`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `service_id` | `SftpServiceId` | Yes | — | No |

Synthetic representation:

```json
{
  "service_id": {}
}
```

<!-- api-model: CompatibilityResult -->
## `CompatibilityResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Compatibility result for one client/core protocol pairing.

**Related methods:** `get_capabilities`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `compatible` | `bool` | Yes | — | No |
| `protocol_version` | `str` | Yes | — | No |
| `message` | `str` | No | `` | No |

Synthetic representation:

```json
{
  "compatible": false,
  "message": "",
  "protocol_version": "example"
}
```

<!-- api-model: ConfirmationPrompt -->
## `ConfirmationPrompt`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `ConfirmationPrompt` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `text` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "text": "example"
}
```

<!-- api-model: ConnectionDetails -->
## `ConnectionDetails`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Full v1 connection response without secret values or sensitive paths.

**Related methods:** `create_connection`, `get_connection`, `update_connection`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `id` | `ConnectionId` | Yes | — | No |
| `nickname` | `str` | Yes | — | No |
| `host` | `str` | Yes | — | No |
| `hostname` | `str` | Yes | — | No |
| `username` | `str` | Yes | — | No |
| `port` | `int` | Yes | — | No |
| `protocol` | `str` | No | `ssh` | No |
| `health` | `ConnectionHealth` | No | `unknown` | No |
| `groups` | `tuple[GroupReference, ...]` | No | `[]` | No |
| `display_name` | `str` | No | `` | No |
| `aliases` | `tuple[str, ...]` | No | `[]` | No |
| `authentication_method` | `AuthenticationMethod` | No | `key` | No |
| `identity_configured` | `bool` | No | `false` | No |
| `certificate_configured` | `bool` | No | `false` | No |
| `x11_forwarding` | `bool` | No | `false` | No |
| `forwarding_rule_count` | `int` | No | `0` | No |
| `proxy_jump` | `tuple[str, ...]` | No | `[]` | No |

Synthetic representation:

```json
{
  "aliases": [],
  "authentication_method": "key",
  "certificate_configured": false,
  "display_name": "",
  "forwarding_rule_count": 0,
  "groups": [],
  "health": "unknown",
  "host": "example",
  "hostname": "example.invalid",
  "id": "production",
  "identity_configured": false,
  "nickname": "example",
  "port": 22,
  "protocol": "ssh",
  "proxy_jump": [],
  "username": "user",
  "x11_forwarding": false
}
```

<!-- api-model: ConnectionEditorCapabilities -->
## `ConnectionEditorCapabilities`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Which connection-editor features the daemon currently supports.

Advertised in the handshake response. The frontend enables/disables
controls based on this.  During incremental rollout ``writable_fields``
grows as each category lands.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `writable_fields` | `frozenset[str]` | No | `[]` | No |
| `supports_secrets` | `bool` | No | `false` | No |
| `supports_metadata` | `bool` | No | `false` | No |
| `supports_groups` | `bool` | No | `false` | No |
| `supports_split` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "supports_groups": false,
  "supports_metadata": false,
  "supports_secrets": false,
  "supports_split": false,
  "writable_fields": []
}
```

<!-- api-model: ConnectionEditorDetails -->
## `ConnectionEditorDetails`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Full editor state for local authenticated clients.

Contains filesystem paths and complete configuration.  Not safe for
untrusted consumers.  Gated behind ``CONNECTIONS_CONFIG_READ``.

**Related methods:** `get_connection_editor`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `id` | `ConnectionId` | Yes | — | No |
| `nickname` | `str` | Yes | — | No |
| `host` | `str` | Yes | — | No |
| `hostname` | `str` | Yes | — | No |
| `username` | `str` | Yes | — | No |
| `port` | `int` | Yes | — | No |
| `protocol` | `str` | No | `ssh` | No |
| `health` | `ConnectionHealth` | No | `unknown` | No |
| `groups` | `tuple[GroupReference, ...]` | No | `[]` | No |
| `display_name` | `str` | No | `` | No |
| `aliases` | `tuple[str, ...]` | No | `[]` | No |
| `authentication_method` | `AuthenticationMethod` | No | `key` | No |
| `identity_configured` | `bool` | No | `false` | No |
| `certificate_configured` | `bool` | No | `false` | No |
| `x11_forwarding` | `bool` | No | `false` | No |
| `forwarding_rule_count` | `int` | No | `0` | No |
| `proxy_jump` | `tuple[str, ...]` | No | `[]` | No |
| `key_select_mode` | `int` | No | `0` | No |
| `identity_files` | `tuple[str, ...]` | No | `[]` | No |
| `certificate_files` | `tuple[str, ...]` | No | `[]` | No |
| `identity_agent` | `str` | No | `` | No |
| `add_keys_to_agent` | `str` | No | `` | No |
| `pkcs11_provider` | `str` | No | `` | No |
| `security_key_provider` | `str` | No | `` | No |
| `pubkey_auth_no` | `bool` | No | `false` | No |
| `forward_agent` | `bool` | No | `false` | No |
| `forward_agent_explicit_no` | `bool` | No | `false` | No |
| `forward_agent_target` | `str` | No | `` | No |
| `proxy_command` | `str` | No | `` | No |
| `forwarding_rules` | `tuple[ForwardingRule, ...]` | No | `[]` | No |
| `pre_command` | `str` | No | `` | No |
| `local_command` | `str` | No | `` | No |
| `remote_command` | `str` | No | `` | No |
| `request_tty` | `str` | No | `` | No |
| `extra_ssh_config` | `str` | No | `` | No |
| `identity_file_none` | `bool` | No | `false` | No |
| `x11_forwarding_explicit_no` | `bool` | No | `false` | No |
| `identities_only_explicit_no` | `bool` | No | `false` | No |
| `preferred_authentications` | `str` | No | `` | No |
| `source` | `str` | No | `` | No |
| `generation` | `int` | No | `0` | No |

Synthetic representation:

```json
{
  "add_keys_to_agent": "",
  "aliases": [],
  "authentication_method": "key",
  "certificate_configured": false,
  "certificate_files": [],
  "display_name": "",
  "extra_ssh_config": "",
  "forward_agent": false,
  "forward_agent_explicit_no": false,
  "forward_agent_target": "",
  "forwarding_rule_count": 0,
  "forwarding_rules": [],
  "generation": 0,
  "groups": [],
  "health": "unknown",
  "host": "example",
  "hostname": "example.invalid",
  "id": "production",
  "identities_only_explicit_no": false,
  "identity_agent": "",
  "identity_configured": false,
  "identity_file_none": false,
  "identity_files": [],
  "key_select_mode": 0,
  "local_command": "",
  "nickname": "example",
  "pkcs11_provider": "",
  "port": 22,
  "pre_command": "",
  "preferred_authentications": "",
  "protocol": "ssh",
  "proxy_command": "",
  "proxy_jump": [],
  "pubkey_auth_no": false,
  "remote_command": "",
  "request_tty": "",
  "security_key_provider": "",
  "source": "",
  "username": "user",
  "x11_forwarding": false,
  "x11_forwarding_explicit_no": false
}
```

<!-- api-model: ConnectionMetadataSummary -->
## `ConnectionMetadataSummary`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Safe per-connection metadata (tags, pinning, WoL). Values never repr'd.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `values` | `Mapping[str, Any]` | No | `{}` | No |

Synthetic representation:

```json
{
  "connection_id": "production",
  "values": {}
}
```

<!-- api-model: ConnectionMutationResult -->
## `ConnectionMutationResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** The authoritative result of a successful connection save.

**Related methods:** `create_connection`, `duplicate_connection`, `split_connection`, `update_connection`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `str` | Yes | — | No |
| `nickname` | `str` | Yes | — | No |
| `generation` | `int` | Yes | — | No |
| `changed` | `bool` | No | `true` | No |
| `changed_fields` | `tuple[str, ...]` | No | `[]` | No |
| `display_name` | `str` | No | `` | No |

Synthetic representation:

```json
{
  "changed": true,
  "changed_fields": [],
  "connection_id": "production",
  "display_name": "",
  "generation": 0,
  "nickname": "example"
}
```

<!-- api-model: ConnectionStoreSnapshot -->
## `ConnectionStoreSnapshot`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** The complete daemon-owned connection store, revisioned by generation.

**Related methods:** `get_connection_store_snapshot`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `generation` | `int` | Yes | — | No |
| `connections` | `Tuple['ConnectionSummary', ...]` | Yes | — | No |
| `groups` | `Tuple[GroupSummary, ...]` | Yes | — | No |
| `root_connection_ids` | `Tuple[ConnectionId, ...]` | Yes | — | No |
| `metadata` | `Tuple[ConnectionMetadataSummary, ...]` | Yes | — | No |

Synthetic representation:

```json
{
  "connections": {},
  "generation": {},
  "groups": {},
  "metadata": {},
  "root_connection_ids": {}
}
```

<!-- api-model: ConnectionSummary -->
## `ConnectionSummary`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** The deliberate, secret-free connection shape used by list views.

**Related methods:** `list_connections`
**Related events:** `connection.created`, `connection.updated`, `connection.deleted`

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `id` | `ConnectionId` | Yes | — | No |
| `nickname` | `str` | Yes | — | No |
| `host` | `str` | Yes | — | No |
| `hostname` | `str` | Yes | — | No |
| `username` | `str` | Yes | — | No |
| `port` | `int` | Yes | — | No |
| `protocol` | `str` | No | `ssh` | No |
| `health` | `ConnectionHealth` | No | `unknown` | No |
| `groups` | `tuple[GroupReference, ...]` | No | `[]` | No |
| `display_name` | `str` | No | `` | No |

Synthetic representation:

```json
{
  "display_name": "",
  "groups": [],
  "health": "unknown",
  "host": "example",
  "hostname": "example.invalid",
  "id": "production",
  "nickname": "example",
  "port": 22,
  "protocol": "ssh",
  "username": "user"
}
```

<!-- api-model: ConnectionValidationError -->
## `ConnectionValidationError`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `ConnectionValidationError` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `field` | `str` | Yes | — | No |
| `code` | `str` | Yes | — | No |
| `message` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "code": "example",
  "field": "example",
  "message": "Example request"
}
```

<!-- api-model: ConnectionValidationResult -->
## `ConnectionValidationResult`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `ConnectionValidationResult` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `valid` | `bool` | Yes | — | No |
| `errors` | `tuple[ConnectionValidationError, ...]` | No | `[]` | No |

Synthetic representation:

```json
{
  "errors": [],
  "valid": false
}
```

<!-- api-model: CopyConnectionToGroupRequest -->
## `CopyConnectionToGroupRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Copy a connection into a group, preserving existing memberships.

**Related methods:** `copy_connection_to_group`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `group_id` | `GroupId` | Yes | — | No |

Synthetic representation:

```json
{
  "connection_id": "production",
  "group_id": {}
}
```

<!-- api-model: CoreEvent -->
## `CoreEvent`

**Status:** Partially implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `CoreEvent` record.

**Related methods:** `subscribe_events`
**Related events:** `connection.created`, `connection.updated`, `connection.deleted`, `connection_store.changed`, `session.created`, `session.state_changed`, `session.output`, `session.interaction_requested`, `session.exited`, `session.closed`, `interaction.created`, `interaction.state_changed`, `sftp.created`, `sftp.state_changed`, `sftp.closed`, `sftp.failed`, `transfer.created`, `transfer.started`, `transfer.progress`, `transfer.item_completed`, `transfer.completed`, `transfer.cancelled`, `transfer.failed`, `forward.created`, `forward.starting`, `forward.active`, `forward.closed`, `forward.failed`, `operation.created`, `operation.state_changed`, `broadcast.output`, `daemon.state_changed`, `error.occurred`

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `type` | `EventType` | Yes | — | No |
| `payload` | `PayloadT` | Yes | — | Yes |
| `sequence` | `int` | Yes | — | No |
| `timestamp` | `datetime` | No | `<UTC timestamp at creation>` | No |
| `request_id` | `RequestId | None` | No | `null` | No |
| `connection_id` | `ConnectionId | None` | No | `null` | No |
| `session_id` | `SessionId | None` | No | `null` | No |

Synthetic representation:

```json
{
  "connection_id": null,
  "payload": "<sensitive value omitted>",
  "request_id": null,
  "sequence": 0,
  "session_id": null,
  "timestamp": "<UTC timestamp at creation>",
  "type": "connection.created"
}
```

<!-- api-model: CoreInfo -->
## `CoreInfo`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Describes the core implementation reached by a client.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `name` | `str` | Yes | — | No |
| `version` | `str` | Yes | — | No |
| `implementation` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "implementation": "example",
  "name": "example",
  "version": "1.0"
}
```

<!-- api-model: CreateConnectionRequest -->
## `CreateConnectionRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `CreateConnectionRequest` record.

**Related methods:** `create_connection`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `nickname` | `str` | Yes | — | No |
| `hostname` | `str` | Yes | — | No |
| `username` | `str` | No | `` | No |
| `port` | `int` | No | `22` | No |
| `protocol` | `str` | No | `ssh` | No |
| `display_name` | `str` | No | `` | No |
| `config_patch` | `Mapping[str, Any]` | No | `{}` | No |
| `plugin_data` | `Mapping[str, Any]` | No | `{}` | No |

Synthetic representation:

```json
{
  "config_patch": {},
  "display_name": "",
  "hostname": "example.invalid",
  "nickname": "example",
  "plugin_data": {},
  "port": 22,
  "protocol": "ssh",
  "username": ""
}
```

<!-- api-model: CreateGroupRequest -->
## `CreateGroupRequest`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Create a new group.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `name` | `str` | Yes | — | No |
| `parent_id` | `str` | No | `` | No |
| `color` | `str` | No | `` | No |

Synthetic representation:

```json
{
  "color": "",
  "name": "example",
  "parent_id": ""
}
```

<!-- api-model: DaemonDiagnostics -->
## `DaemonDiagnostics`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `DaemonDiagnostics` record.

**Related methods:** `get_daemon_diagnostics`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `status` | `DaemonStatus` | Yes | — | No |
| `uptime_seconds` | `float` | Yes | — | No |
| `executor_queue_depth` | `int` | No | `0` | No |
| `thread_counts_by_role` | `Mapping[str, int]` | No | `{}` | No |
| `open_descriptor_count` | `Optional[int]` | No | `null` | No |
| `rss_bytes` | `Optional[int]` | No | `null` | No |
| `socket_bound` | `bool` | No | `true` | No |
| `keep_alive_lease` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "executor_queue_depth": 0,
  "keep_alive_lease": false,
  "open_descriptor_count": null,
  "rss_bytes": null,
  "socket_bound": true,
  "status": {},
  "thread_counts_by_role": {},
  "uptime_seconds": {}
}
```

<!-- api-model: DaemonIdleInfo -->
## `DaemonIdleInfo`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `DaemonIdleInfo` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `idle_shutdown_enabled` | `bool` | Yes | — | No |
| `idle_shutdown_seconds` | `Optional[float]` | Yes | — | No |
| `idle_since` | `Optional[datetime]` | No | `null` | No |
| `idle_deadline` | `Optional[datetime]` | No | `null` | No |
| `idle_blockers` | `Tuple[str, ...]` | No | `[]` | No |

Synthetic representation:

```json
{
  "idle_blockers": [],
  "idle_deadline": null,
  "idle_shutdown_enabled": {},
  "idle_shutdown_seconds": {},
  "idle_since": null
}
```

<!-- api-model: DaemonResourceCounts -->
## `DaemonResourceCounts`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `DaemonResourceCounts` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `clients` | `int` | No | `0` | No |
| `sessions_active` | `int` | No | `0` | No |
| `sessions_retained` | `int` | No | `0` | No |
| `sftp_active` | `int` | No | `0` | No |
| `sftp_retained` | `int` | No | `0` | No |
| `transfers_queued` | `int` | No | `0` | No |
| `transfers_starting` | `int` | No | `0` | No |
| `transfers_running` | `int` | No | `0` | No |
| `transfers_retained` | `int` | No | `0` | No |
| `forwards_active` | `int` | No | `0` | No |
| `forwards_retained` | `int` | No | `0` | No |
| `interactions_pending` | `int` | No | `0` | No |

Synthetic representation:

```json
{
  "clients": 0,
  "forwards_active": 0,
  "forwards_retained": 0,
  "interactions_pending": 0,
  "sessions_active": 0,
  "sessions_retained": 0,
  "sftp_active": 0,
  "sftp_retained": 0,
  "transfers_queued": 0,
  "transfers_retained": 0,
  "transfers_running": 0,
  "transfers_starting": 0
}
```

<!-- api-model: DaemonStatus -->
## `DaemonStatus`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `DaemonStatus` record.

**Related methods:** `get_daemon_status`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `state` | `DaemonLifecycleState` | Yes | — | No |
| `server_instance_id` | `str` | Yes | — | No |
| `started_at` | `datetime` | Yes | — | No |
| `protocol_version` | `str` | Yes | — | No |
| `api_implementation_version` | `str` | Yes | — | No |
| `daemon_version` | `str` | Yes | — | No |
| `development_revision` | `str` | Yes | — | No |
| `resources` | `DaemonResourceCounts` | Yes | — | No |
| `idle` | `DaemonIdleInfo` | Yes | — | No |
| `shutdown_deadline` | `Optional[datetime]` | No | `null` | No |
| `disconnect_reason` | `Optional[str]` | No | `null` | No |
| `restart_requested` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "api_implementation_version": {},
  "daemon_version": {},
  "development_revision": {},
  "disconnect_reason": null,
  "idle": {},
  "protocol_version": {},
  "resources": {},
  "restart_requested": false,
  "server_instance_id": {},
  "shutdown_deadline": null,
  "started_at": {},
  "state": {}
}
```

<!-- api-model: DaemonStopResult -->
## `DaemonStopResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `DaemonStopResult` record.

**Related methods:** `restart_daemon`, `stop_daemon`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `accepted` | `bool` | Yes | — | No |
| `state` | `DaemonLifecycleState` | Yes | — | No |
| `resources` | `DaemonResourceCounts` | Yes | — | No |
| `will_lose` | `Tuple[str, ...]` | No | `[]` | No |
| `confirmation` | `Optional[str]` | No | `null` | No |
| `message` | `str` | No | `` | No |
| `restart_requested` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "accepted": {},
  "confirmation": null,
  "message": "",
  "resources": {},
  "restart_requested": false,
  "state": {},
  "will_lose": []
}
```

<!-- api-model: DeleteConnectionPasswordRequest -->
## `DeleteConnectionPasswordRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Delete all stored login passwords for a connection.

**Related methods:** `delete_connection_password`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `previous_hostname` | `str` | No | `` | No |
| `previous_host` | `str` | No | `` | No |
| `previous_username` | `str` | No | `` | No |

Synthetic representation:

```json
{
  "connection_id": "production",
  "previous_host": "",
  "previous_hostname": "",
  "previous_username": ""
}
```

<!-- api-model: DeleteConnectionRequest -->
## `DeleteConnectionRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `DeleteConnectionRequest` record.

**Related methods:** `delete_connection`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |

Synthetic representation:

```json
{
  "connection_id": "production"
}
```

<!-- api-model: DeleteConnectionResult -->
## `DeleteConnectionResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `DeleteConnectionResult` record.

**Related methods:** `delete_connection`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `deleted` | `bool` | Yes | — | No |

Synthetic representation:

```json
{
  "connection_id": "production",
  "deleted": false
}
```

<!-- api-model: DeleteGroupRequest -->
## `DeleteGroupRequest`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Delete a group.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `group_id` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "group_id": "example"
}
```

<!-- api-model: DeleteKeyPassphraseRequest -->
## `DeleteKeyPassphraseRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Request to delete an SSH key passphrase.

**Related methods:** `delete_key_passphrase`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `key_path` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "key_path": "example"
}
```

<!-- api-model: DeleteKeyRequest -->
## `DeleteKeyRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Request deletion of one daemon-known key by opaque identity.

**Related methods:** `delete_key`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `key_id` | `KeyId` | Yes | — | No |
| `scope` | `KeyStoreScope` | No | `default` | No |

Synthetic representation:

```json
{
  "key_id": {},
  "scope": "default"
}
```

<!-- api-model: DeleteKeyResult -->
## `DeleteKeyResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Stable result for daemon-owned key-pair deletion.

**Related methods:** `delete_key`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `key_id` | `KeyId` | Yes | — | No |
| `deleted` | `bool` | No | `true` | No |

Synthetic representation:

```json
{
  "deleted": true,
  "key_id": {}
}
```

<!-- api-model: DeletePluginSecretRequest -->
## `DeletePluginSecretRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `DeletePluginSecretRequest` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `plugin_id` | `str` | Yes | — | No |
| `key` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "key": "example",
  "plugin_id": "example.plugin"
}
```

<!-- api-model: DetachSessionRequest -->
## `DetachSessionRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `DetachSessionRequest` record.

**Related methods:** `detach_session`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `session_id` | `SessionId` | Yes | — | No |
| `attachment_id` | `AttachmentId` | Yes | — | No |

Synthetic representation:

```json
{
  "attachment_id": "attachment-2",
  "session_id": "session-12"
}
```

<!-- api-model: EffectiveConfigComparison -->
## `EffectiveConfigComparison`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Daemon-owned authored-vs-effective OpenSSH comparison.

**Related methods:** `get_effective_config`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `str` | Yes | — | No |
| `host` | `str` | Yes | — | No |
| `available` | `bool` | Yes | — | No |
| `has_diff` | `bool` | No | `false` | No |
| `changes` | `tuple[dict[str, Any], ...]` | No | `[]` | No |
| `own` | `tuple[str, ...]` | No | `[]` | No |
| `full` | `tuple[str, ...]` | No | `[]` | No |
| `generation` | `int` | No | `0` | No |

Synthetic representation:

```json
{
  "available": false,
  "changes": [],
  "connection_id": "production",
  "full": [],
  "generation": 0,
  "has_diff": false,
  "host": "example",
  "own": []
}
```

<!-- api-model: ErrorData -->
## `ErrorData`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Wire-safe representation of :class:`SshPilotError`.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `code` | `ErrorCode` | Yes | — | No |
| `message` | `str` | Yes | — | No |
| `details` | `Mapping[str, Any]` | No | `{}` | Yes |
| `retryable` | `bool` | No | `false` | No |
| `request_id` | `Optional[RequestId]` | No | `null` | No |
| `connection_id` | `Optional[ConnectionId]` | No | `null` | No |
| `session_id` | `Optional[SessionId]` | No | `null` | No |

Synthetic representation:

```json
{
  "code": {},
  "connection_id": null,
  "details": "<sensitive value omitted>",
  "message": "Example request",
  "request_id": null,
  "retryable": false,
  "session_id": null
}
```

<!-- api-model: ErrorResponseEnvelope -->
## `ErrorResponseEnvelope`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** A structured failed response correlated to one request.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `protocol_version` | `str` | Yes | — | No |
| `request_id` | `RequestId` | Yes | — | No |
| `error` | `ErrorData` | Yes | — | Yes |

Synthetic representation:

```json
{
  "error": "<sensitive value omitted>",
  "protocol_version": {},
  "request_id": "request-3"
}
```

<!-- api-model: EventEnvelope -->
## `EventEnvelope`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** An unsolicited typed public event frame.

Protocol v1 currently carries typed connection and session lifecycle
events. Terminal bytes, prompts, and replay remain outside this envelope.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `protocol_version` | `str` | Yes | — | No |
| `event` | `str` | Yes | — | No |
| `sequence` | `int` | Yes | — | No |
| `payload` | `Mapping[str, Any]` | No | `{}` | Yes |

Synthetic representation:

```json
{
  "event": {},
  "payload": "<sensitive value omitted>",
  "protocol_version": {},
  "sequence": 0
}
```

<!-- api-model: ExternalTerminalLaunchSpec -->
## `ExternalTerminalLaunchSpec`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Daemon-prepared, non-secret launch data for an external terminal.

**Related methods:** `prepare_external_terminal_launch`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `argv` | `tuple[str, ...]` | Yes | — | No |
| `environment` | `tuple[tuple[str, str], ...]` | No | `[]` | No |
| `display_name` | `str` | No | `` | No |
| `secret_autofill_supported` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "argv": [],
  "display_name": "",
  "environment": [],
  "secret_autofill_supported": false
}
```

<!-- api-model: ForwardSummary -->
## `ForwardSummary`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `ForwardSummary` record.

**Related methods:** `claim_forward`, `get_forward`, `list_forwards`, `open_forward`
**Related events:** `forward.created`, `forward.starting`, `forward.active`, `forward.closed`, `forward.failed`

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `id` | `ForwardId` | Yes | — | No |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `type` | `ForwardType` | Yes | — | No |
| `state` | `ForwardState` | Yes | — | No |
| `bind_host` | `str` | Yes | — | No |
| `bind_port` | `int` | Yes | — | No |
| `destination_host` | `Optional[str]` | No | `null` | No |
| `destination_port` | `Optional[int]` | No | `null` | No |
| `created_at` | `datetime` | No | `<UTC timestamp at creation>` | No |
| `active_at` | `Optional[datetime]` | No | `null` | No |
| `closed_at` | `Optional[datetime]` | No | `null` | No |
| `owner_client_id` | `Optional[ClientId]` | No | `null` | No |
| `failure` | `Optional[ServiceFailure]` | No | `null` | No |
| `session_id` | `Optional[SessionId]` | No | `null` | No |

Synthetic representation:

```json
{
  "active_at": null,
  "bind_host": "127.0.0.1",
  "bind_port": 8022,
  "closed_at": null,
  "connection_id": "production",
  "created_at": "<UTC timestamp at creation>",
  "destination_host": null,
  "destination_port": null,
  "failure": null,
  "id": "production",
  "owner_client_id": null,
  "session_id": null,
  "state": {},
  "type": {}
}
```

<!-- api-model: ForwardingRule -->
## `ForwardingRule`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** One port-forwarding rule.

The field names exactly match the existing dict schema used by
``format_ssh_config_entry`` and ``_parse_forwarding_rules_from_config``
so that round-tripping through the daemon is lossless.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `type` | `str` | Yes | — | No |
| `listen_port` | `int` | Yes | — | No |
| `listen_addr` | `str` | No | `` | No |
| `remote_host` | `str` | No | `` | No |
| `remote_port` | `int` | No | `0` | No |
| `local_host` | `str` | No | `` | No |
| `local_port` | `int` | No | `0` | No |
| `enabled` | `bool` | No | `true` | No |
| `socks` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "enabled": true,
  "listen_addr": "",
  "listen_port": 0,
  "local_host": "",
  "local_port": 0,
  "remote_host": "",
  "remote_port": 0,
  "socks": false,
  "type": "example"
}
```

<!-- api-model: GenerateKeyRequest -->
## `GenerateKeyRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Request a daemon-owned ``ssh-keygen`` invocation.

**Related methods:** `generate_key`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `name` | `str` | Yes | — | No |
| `key_type` | `str` | No | `ed25519` | No |
| `key_size` | `int` | No | `0` | No |
| `comment` | `str` | No | `` | No |
| `encrypted` | `bool` | No | `false` | No |
| `interaction_scope_id` | `SessionId | None` | No | `null` | No |
| `scope` | `KeyStoreScope` | No | `default` | No |

Synthetic representation:

```json
{
  "comment": "",
  "encrypted": false,
  "interaction_scope_id": null,
  "key_size": 0,
  "key_type": "ed25519",
  "name": "example",
  "scope": "default"
}
```

<!-- api-model: GenerateKeyResult -->
## `GenerateKeyResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Result of a daemon key generation.

**Related methods:** `generate_key`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `key` | `KeySummary` | Yes | — | No |

Synthetic representation:

```json
{
  "key": {}
}
```

<!-- api-model: GetPluginSecretRequest -->
## `GetPluginSecretRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `GetPluginSecretRequest` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `plugin_id` | `str` | Yes | — | No |
| `key` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "key": "example",
  "plugin_id": "example.plugin"
}
```

<!-- api-model: GroupReference -->
## `GroupReference`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `GroupReference` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `id` | `str` | Yes | — | No |
| `name` | `str` | No | `` | No |

Synthetic representation:

```json
{
  "id": "production",
  "name": ""
}
```

<!-- api-model: GroupSummary -->
## `GroupSummary`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** One connection group in the daemon-owned store.

Group expansion is deliberately absent: it is visual frontend state.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `id` | `GroupId` | Yes | — | No |
| `name` | `str` | Yes | — | No |
| `parent_id` | `Optional[GroupId]` | No | `null` | No |
| `order` | `int` | No | `0` | No |
| `color` | `str` | No | `` | No |
| `connection_ids` | `Tuple[ConnectionId, ...]` | No | `[]` | No |

Synthetic representation:

```json
{
  "color": "",
  "connection_ids": [],
  "id": "production",
  "name": "example",
  "order": 0,
  "parent_id": null
}
```

<!-- api-model: HandshakeRequest -->
## `HandshakeRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Validated client metadata supplied before ordinary RPC methods.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `client_name` | `str` | Yes | — | No |
| `client_version` | `str` | Yes | — | No |
| `supported_protocol_versions` | `Tuple[str, ...]` | Yes | — | No |
| `client_capabilities` | `FrozenSet[str]` | No | `[]` | No |
| `frontend_type` | `Optional[str]` | No | `null` | No |
| `supported_frame_types` | `FrozenSet[str]` | No | `[]` | No |

Synthetic representation:

```json
{
  "client_capabilities": [],
  "client_name": {},
  "client_version": {},
  "frontend_type": null,
  "supported_frame_types": [],
  "supported_protocol_versions": {}
}
```

<!-- api-model: HandshakeResult -->
## `HandshakeResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Daemon identity and the selected Protocol v1 contract.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `daemon_version` | `str` | Yes | — | No |
| `core_version` | `str` | Yes | — | No |
| `selected_protocol_version` | `str` | Yes | — | No |
| `daemon_capabilities` | `FrozenSet[Capability]` | Yes | — | No |
| `compatibility_status` | `str` | Yes | — | No |
| `server_instance_id` | `str` | Yes | — | No |
| `daemon_started_at` | `str` | No | `` | No |
| `development_revision` | `str` | No | `` | No |
| `api_implementation_version` | `str` | No | `` | No |

Synthetic representation:

```json
{
  "api_implementation_version": "",
  "compatibility_status": {},
  "core_version": {},
  "daemon_capabilities": {},
  "daemon_started_at": "",
  "daemon_version": {},
  "development_revision": "",
  "selected_protocol_version": {},
  "server_instance_id": {}
}
```

<!-- api-model: HostKeyPrompt -->
## `HostKeyPrompt`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `HostKeyPrompt` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `hostname` | `str` | Yes | — | No |
| `port` | `int` | Yes | — | No |
| `key_type` | `str` | Yes | — | No |
| `fingerprint` | `str` | Yes | — | No |
| `status` | `HostKeyStatus` | Yes | — | No |

Synthetic representation:

```json
{
  "fingerprint": "example",
  "hostname": "example.invalid",
  "key_type": "example",
  "port": 22,
  "status": "unknown"
}
```

<!-- api-model: InputOwner -->
## `InputOwner`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `InputOwner` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `client_id` | `ClientId` | Yes | — | No |
| `attachment_id` | `AttachmentId` | Yes | — | No |

Synthetic representation:

```json
{
  "attachment_id": "attachment-2",
  "client_id": "client-abc123"
}
```

<!-- api-model: InteractionCancellation -->
## `InteractionCancellation`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `InteractionCancellation` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `interaction_id` | `InteractionId` | Yes | — | No |
| `reason` | `str` | No | `` | No |

Synthetic representation:

```json
{
  "interaction_id": "interaction-4",
  "reason": ""
}
```

<!-- api-model: InteractionClaim -->
## `InteractionClaim`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `InteractionClaim` record.

**Related methods:** `claim_interaction`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `interaction_id` | `InteractionId` | Yes | — | No |
| `responder_client_id` | `ClientId` | Yes | — | No |
| `nonce` | `str` | Yes | — | No |
| `expires_at` | `datetime` | Yes | — | No |

Synthetic representation:

```json
{
  "expires_at": null,
  "interaction_id": "interaction-4",
  "nonce": "example",
  "responder_client_id": "client-abc123"
}
```

<!-- api-model: InteractionDecisionRequest -->
## `InteractionDecisionRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `InteractionDecisionRequest` record.

**Related methods:** `respond_to_interaction`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `interaction_id` | `InteractionId` | Yes | — | No |
| `host_key_decision` | `HostKeyDecision | None` | No | `null` | No |
| `secret_decision` | `SecretDecision | None` | No | `null` | No |
| `remember_policy` | `RememberPolicy` | No | `do_not_store` | No |

Synthetic representation:

```json
{
  "host_key_decision": null,
  "interaction_id": "interaction-4",
  "remember_policy": "do_not_store",
  "secret_decision": null
}
```

<!-- api-model: InteractionRejection -->
## `InteractionRejection`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `InteractionRejection` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `interaction_id` | `InteractionId` | Yes | — | No |
| `reason` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "interaction_id": "interaction-4",
  "reason": "example"
}
```

<!-- api-model: InteractionRequest -->
## `InteractionRequest`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `InteractionRequest` record.

**Related methods:** None
**Related events:** `session.interaction_requested`

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `id` | `InteractionId` | Yes | — | No |
| `request_id` | `RequestId` | Yes | — | No |
| `kind` | `InteractionKind` | Yes | — | No |
| `message` | `str` | Yes | — | No |
| `secret` | `bool` | Yes | — | No |
| `allow_empty` | `bool` | No | `false` | No |
| `choices` | `tuple[str, ...]` | No | `[]` | No |
| `session_id` | `SessionId | None` | No | `null` | No |
| `originating_client_id` | `ClientId | None` | No | `null` | No |
| `created_at` | `datetime` | No | `<UTC timestamp at creation>` | No |
| `expires_at` | `datetime | None` | No | `null` | No |
| `status` | `InteractionStatus` | No | `pending` | No |

Synthetic representation:

```json
{
  "allow_empty": false,
  "choices": [],
  "created_at": "<UTC timestamp at creation>",
  "expires_at": null,
  "id": "production",
  "kind": "password",
  "message": "Example request",
  "originating_client_id": null,
  "request_id": "request-3",
  "secret": false,
  "session_id": null,
  "status": "pending"
}
```

<!-- api-model: InteractionResponse -->
## `InteractionResponse`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `InteractionResponse` record.

**Related methods:** `respond_to_interaction`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `interaction_id` | `InteractionId` | Yes | — | No |
| `status` | `InteractionStatus` | Yes | — | No |
| `value` | `str | None` | No | `null` | Yes |
| `choice` | `str | None` | No | `null` | No |

Synthetic representation:

```json
{
  "choice": null,
  "interaction_id": "interaction-4",
  "status": "pending",
  "value": "<sensitive value omitted>"
}
```

<!-- api-model: InteractionSummary -->
## `InteractionSummary`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `InteractionSummary` record.

**Related methods:** `get_interaction`, `list_interactions`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `id` | `InteractionId` | Yes | — | No |
| `session_id` | `SessionId` | Yes | — | No |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `type` | `InteractionType` | Yes | — | No |
| `state` | `InteractionState` | Yes | — | No |
| `created_at` | `datetime` | Yes | — | No |
| `expires_at` | `datetime` | Yes | — | No |
| `attempt` | `int` | Yes | — | No |
| `prompt` | `HostKeyPrompt | PasswordPrompt | PassphrasePrompt | ChallengePrompt | PresencePrompt | ConfirmationPrompt` | Yes | — | No |
| `responder_client_id` | `ClientId | None` | No | `null` | No |

Synthetic representation:

```json
{
  "attempt": 0,
  "connection_id": "production",
  "created_at": "2030-01-01T00:00:00Z",
  "expires_at": null,
  "id": "production",
  "prompt": {
    "fingerprint": "example",
    "hostname": "example.invalid",
    "key_type": "example",
    "port": 22,
    "status": "unknown"
  },
  "responder_client_id": null,
  "session_id": "session-12",
  "state": "pending",
  "type": "host_key_confirmation"
}
```

<!-- api-model: InteractionTimeout -->
## `InteractionTimeout`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `InteractionTimeout` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `interaction_id` | `InteractionId` | Yes | — | No |
| `expired_at` | `datetime` | No | `<UTC timestamp at creation>` | No |

Synthetic representation:

```json
{
  "expired_at": "<UTC timestamp at creation>",
  "interaction_id": "interaction-4"
}
```

<!-- api-model: KeyList -->
## `KeyList`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Ordered key metadata from the daemon (duplicate ids rejected).

**Related methods:** `list_keys`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `keys` | `Tuple[KeySummary, ...]` | Yes | — | No |

Synthetic representation:

```json
{
  "keys": {}
}
```

<!-- api-model: KeySummary -->
## `KeySummary`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Metadata for a daemon-discovered or generated key (never private material).

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `key_id` | `KeyId` | Yes | — | No |
| `name` | `str` | Yes | — | No |
| `private_path` | `str` | Yes | — | No |
| `public_path` | `str` | Yes | — | No |
| `public_key_available` | `bool` | Yes | — | No |

Synthetic representation:

```json
{
  "key_id": {},
  "name": "example",
  "private_path": {},
  "public_key_available": {},
  "public_path": {}
}
```

<!-- api-model: KnownHostEntrySummary -->
## `KnownHostEntrySummary`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** One displayed known-hosts line (never the raw file handle).

**Related methods:** `list_known_hosts`, `remove_known_host_entries`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `entry_id` | `KnownHostEntryId` | Yes | — | No |
| `hostname` | `str` | Yes | — | No |
| `key_type` | `str` | Yes | — | No |
| `display_line` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "display_line": "example",
  "entry_id": "id:example",
  "hostname": "example.invalid",
  "key_type": "example"
}
```

<!-- api-model: KnownHostsMutationResult -->
## `KnownHostsMutationResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Result of a committed removal, re-read from the authoritative file.

**Related methods:** `remove_known_host_entries`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `revision` | `str` | Yes | — | No |
| `removed_count` | `int` | Yes | — | No |
| `entries` | `tuple[KnownHostEntrySummary, ...]` | Yes | — | No |

Synthetic representation:

```json
{
  "entries": [],
  "removed_count": 0,
  "revision": "example"
}
```

<!-- api-model: KnownHostsSnapshot -->
## `KnownHostsSnapshot`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** The full known-hosts document projected for display.

**Related methods:** `list_known_hosts`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `revision` | `str` | Yes | — | No |
| `entries` | `tuple[KnownHostEntrySummary, ...]` | Yes | — | No |

Synthetic representation:

```json
{
  "entries": [],
  "revision": "example"
}
```

<!-- api-model: ListDirectoryRequest -->
## `ListDirectoryRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `ListDirectoryRequest` record.

**Related methods:** `sftp_list_directory`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `path` | `str` | Yes | — | No |
| `service_id` | `Optional[SftpServiceId]` | No | `null` | No |
| `cursor` | `Optional[str]` | No | `null` | No |
| `limit` | `Optional[int]` | No | `null` | No |

Synthetic representation:

```json
{
  "connection_id": "production",
  "cursor": null,
  "limit": null,
  "path": "/remote/example",
  "service_id": null
}
```

<!-- api-model: ListDirectoryResult -->
## `ListDirectoryResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `ListDirectoryResult` record.

**Related methods:** `sftp_list_directory`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `path` | `str` | Yes | — | No |
| `entries` | `Tuple[RemoteFileEntry, ...]` | Yes | — | No |
| `truncated` | `bool` | No | `false` | No |
| `next_cursor` | `Optional[str]` | No | `null` | No |

Synthetic representation:

```json
{
  "entries": {},
  "next_cursor": null,
  "path": "/remote/example",
  "truncated": false
}
```

<!-- api-model: ListKeysRequest -->
## `ListKeysRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** List keys from one semantic key-store scope.

**Related methods:** `list_keys`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `scope` | `KeyStoreScope` | No | `default` | No |

Synthetic representation:

```json
{
  "scope": "default"
}
```

<!-- api-model: LookupKeyPassphraseRequest -->
## `LookupKeyPassphraseRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Look up a stored key passphrase.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `key_path` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "key_path": "example"
}
```

<!-- api-model: MoveConnectionsRequest -->
## `MoveConnectionsRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Place one or more connections with explicit membership semantics.

**Related methods:** `move_connections`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_ids` | `Tuple[ConnectionId, ...]` | Yes | — | No |
| `target_group_id` | `Optional[GroupId]` | No | `null` | No |
| `target_connection_id` | `Optional[ConnectionId]` | No | `null` | No |
| `position` | `Optional[str]` | No | `null` | No |
| `expected_generation` | `Optional[int]` | No | `null` | No |
| `source_group_id` | `Optional[GroupId]` | No | `null` | No |
| `mode` | `ConnectionPlacementMode` | No | `exclusive` | No |

Synthetic representation:

```json
{
  "connection_ids": {},
  "expected_generation": null,
  "mode": "exclusive",
  "position": null,
  "source_group_id": null,
  "target_connection_id": null,
  "target_group_id": null
}
```

<!-- api-model: OpenForwardRequest -->
## `OpenForwardRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `OpenForwardRequest` record.

**Related methods:** `open_forward`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `type` | `ForwardType` | Yes | — | No |
| `bind_host` | `str` | Yes | — | No |
| `bind_port` | `int` | Yes | — | No |
| `destination_host` | `Optional[str]` | No | `null` | No |
| `destination_port` | `Optional[int]` | No | `null` | No |

Synthetic representation:

```json
{
  "bind_host": "127.0.0.1",
  "bind_port": 8022,
  "connection_id": "production",
  "destination_host": null,
  "destination_port": null,
  "type": {}
}
```

<!-- api-model: OpenSessionRequest -->
## `OpenSessionRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `OpenSessionRequest` record.

**Related methods:** `open_session`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `dimensions` | `TerminalDimensions | None` | No | `null` | No |
| `remote_command` | `str | None` | No | `null` | No |
| `force_tty` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "connection_id": "production",
  "dimensions": null,
  "force_tty": false,
  "remote_command": null
}
```

<!-- api-model: OpenSftpRequest -->
## `OpenSftpRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `OpenSftpRequest` record.

**Related methods:** `open_sftp`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |

Synthetic representation:

```json
{
  "connection_id": "production"
}
```

<!-- api-model: OperationModeFiles -->
## `OperationModeFiles`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Resolved, on-disk file paths that back one SSH configuration scope.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `root_config_path` | `str` | Yes | — | No |
| `root_config_exists` | `bool` | Yes | — | No |
| `known_hosts_path` | `str` | Yes | — | No |
| `known_hosts_exists` | `bool` | Yes | — | No |
| `imported_fragment_path` | `str` | Yes | — | No |
| `imported_fragment_exists` | `bool` | Yes | — | No |

Synthetic representation:

```json
{
  "imported_fragment_exists": {},
  "imported_fragment_path": {},
  "known_hosts_exists": {},
  "known_hosts_path": {},
  "root_config_exists": {},
  "root_config_path": {}
}
```

<!-- api-model: OperationModeResult -->
## `OperationModeResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Confirmed mode state or an explicit transition/recovery outcome.

**Related methods:** `get_operation_mode`, `set_operation_mode`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `accepted` | `bool` | Yes | — | No |
| `active_mode` | `OperationMode` | Yes | — | No |
| `generation` | `int` | Yes | — | No |
| `seeded` | `bool` | No | `false` | No |
| `conflict` | `bool` | No | `false` | No |
| `message` | `str` | No | `` | No |
| `target_description` | `str` | No | `` | No |
| `persisted_mode` | `Optional[OperationMode]` | No | `null` | No |
| `rollback_completed` | `bool` | No | `true` | No |
| `recovery_required` | `bool` | No | `false` | No |
| `default_files` | `Optional[OperationModeFiles]` | No | `null` | No |
| `isolated_files` | `Optional[OperationModeFiles]` | No | `null` | No |
| `app_config_path` | `str` | No | `` | No |
| `app_config_exists` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "accepted": {},
  "active_mode": {},
  "app_config_exists": false,
  "app_config_path": "",
  "conflict": false,
  "default_files": null,
  "generation": {},
  "isolated_files": null,
  "message": "",
  "persisted_mode": null,
  "recovery_required": false,
  "rollback_completed": true,
  "seeded": false,
  "target_description": ""
}
```

<!-- api-model: OperationSummary -->
## `OperationSummary`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-safe snapshot of one daemon operation.

**Related methods:** `cancel_operation`, `deploy_key`, `get_operation`, `remove_authorized_key`, `sftp_copy`, `sftp_directory_size`, `sftp_remove`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `operation_id` | `OperationId` | Yes | — | No |
| `kind` | `OperationKind` | Yes | — | No |
| `state` | `OperationState` | Yes | — | No |
| `message` | `str` | Yes | — | No |
| `created_at` | `datetime` | Yes | — | No |
| `connection_id` | `Optional[ConnectionId]` | No | `null` | No |
| `started_at` | `Optional[datetime]` | No | `null` | No |
| `finished_at` | `Optional[datetime]` | No | `null` | No |
| `progress` | `Optional[float]` | No | `null` | No |
| `owner_client_id` | `Optional[ClientId]` | No | `null` | No |
| `failure` | `Optional[ServiceFailure]` | No | `null` | No |
| `result` | `Optional[Dict]` | No | `null` | Yes |

Synthetic representation:

```json
{
  "connection_id": null,
  "created_at": "2030-01-01T00:00:00Z",
  "failure": null,
  "finished_at": null,
  "kind": {},
  "message": "Example request",
  "operation_id": {},
  "owner_client_id": null,
  "progress": null,
  "result": "<sensitive value omitted>",
  "started_at": null,
  "state": {}
}
```

<!-- api-model: PassphrasePrompt -->
## `PassphrasePrompt`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `PassphrasePrompt` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `key_display_name` | `str` | Yes | — | No |
| `key_fingerprint` | `str | None` | Yes | — | No |
| `attempt` | `int` | Yes | — | No |
| `can_remember` | `bool` | Yes | — | No |
| `stored_secret_available` | `bool` | Yes | — | No |
| `confirmation_required` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "attempt": 0,
  "can_remember": false,
  "confirmation_required": false,
  "key_display_name": "example",
  "key_fingerprint": null,
  "stored_secret_available": false
}
```

<!-- api-model: PasswordPrompt -->
## `PasswordPrompt`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `PasswordPrompt` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `username` | `str` | Yes | — | No |
| `hostname` | `str` | Yes | — | No |
| `port` | `int` | Yes | — | No |
| `attempt` | `int` | Yes | — | No |
| `can_remember` | `bool` | Yes | — | No |
| `stored_secret_available` | `bool` | Yes | — | No |

Synthetic representation:

```json
{
  "attempt": 0,
  "can_remember": false,
  "hostname": "example.invalid",
  "port": 22,
  "stored_secret_available": false,
  "username": "user"
}
```

<!-- api-model: PlaceGroupRequest -->
## `PlaceGroupRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Place a group at a parent/index in the sibling order.

**Related methods:** `place_group`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `group_id` | `GroupId` | Yes | — | No |
| `parent_id` | `Optional[GroupId]` | Yes | — | No |
| `index` | `int` | Yes | — | No |
| `expected_generation` | `Optional[int]` | No | `null` | No |

Synthetic representation:

```json
{
  "expected_generation": null,
  "group_id": {},
  "index": {},
  "parent_id": {}
}
```

<!-- api-model: PluginArgument -->
## `PluginArgument`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** One deliberate plugin argument; secret values stay out of ``repr``.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `name` | `str` | Yes | — | No |
| `value` | `str` | Yes | — | Yes |
| `secret` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "name": "example",
  "secret": false,
  "value": "<sensitive value omitted>"
}
```

<!-- api-model: PluginOperationRequest -->
## `PluginOperationRequest`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `PluginOperationRequest` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `request_id` | `RequestId` | Yes | — | No |
| `plugin_id` | `str` | Yes | — | No |
| `operation` | `str` | Yes | — | No |
| `arguments` | `Tuple[PluginArgument, ...]` | No | `[]` | No |

Synthetic representation:

```json
{
  "arguments": [],
  "operation": "status",
  "plugin_id": "example.plugin",
  "request_id": "request-3"
}
```

<!-- api-model: PluginOperationResult -->
## `PluginOperationResult`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `PluginOperationResult` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `request_id` | `RequestId` | Yes | — | No |
| `plugin_id` | `str` | Yes | — | No |
| `values` | `Tuple[Tuple[str, str], ...]` | No | `[]` | Yes |

Synthetic representation:

```json
{
  "plugin_id": "example.plugin",
  "request_id": "request-3",
  "values": "<sensitive value omitted>"
}
```

<!-- api-model: PortForwardSummary -->
## `PortForwardSummary`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Legacy schema-only forward snapshot; prefer :class:`ForwardSummary`.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `id` | `str` | Yes | — | No |
| `session_id` | `SessionId` | Yes | — | No |
| `kind` | `ForwardKind` | Yes | — | No |
| `state` | `ForwardState` | Yes | — | No |
| `bind_host` | `str` | Yes | — | No |
| `bind_port` | `int` | Yes | — | No |
| `target_host` | `str` | No | `` | No |
| `target_port` | `Optional[int]` | No | `null` | No |

Synthetic representation:

```json
{
  "bind_host": "127.0.0.1",
  "bind_port": 8022,
  "id": "production",
  "kind": {},
  "session_id": "session-12",
  "state": {},
  "target_host": "",
  "target_port": null
}
```

<!-- api-model: PresencePrompt -->
## `PresencePrompt`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `PresencePrompt` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `text` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "text": "example"
}
```

<!-- api-model: PublicKeyResult -->
## `PublicKeyResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Public-key text for one key (never private-key material).

**Related methods:** `read_public_key`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `key_id` | `KeyId` | Yes | — | No |
| `text` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "key_id": {},
  "text": {}
}
```

<!-- api-model: ReadPublicKeyRequest -->
## `ReadPublicKeyRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Read public-key text for one opaque key id.

**Related methods:** `read_public_key`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `key_id` | `KeyId` | Yes | — | No |
| `scope` | `KeyStoreScope` | No | `default` | No |

Synthetic representation:

```json
{
  "key_id": {},
  "scope": "default"
}
```

<!-- api-model: ReleaseTerminalInputRequest -->
## `ReleaseTerminalInputRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `ReleaseTerminalInputRequest` record.

**Related methods:** `release_terminal_input`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `session_id` | `SessionId` | Yes | — | No |
| `attachment_id` | `AttachmentId` | Yes | — | No |

Synthetic representation:

```json
{
  "attachment_id": "attachment-2",
  "session_id": "session-12"
}
```

<!-- api-model: RemoteFileEntry -->
## `RemoteFileEntry`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `RemoteFileEntry` record.

**Related methods:** `sftp_list_directory`, `sftp_lstat`, `sftp_stat`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `name` | `str` | Yes | — | No |
| `path` | `str` | Yes | — | No |
| `file_type` | `RemoteFileType` | Yes | — | No |
| `size` | `Optional[int]` | No | `null` | No |
| `mode` | `Optional[int]` | No | `null` | No |
| `uid` | `Optional[int]` | No | `null` | No |
| `gid` | `Optional[int]` | No | `null` | No |
| `modified_at` | `Optional[datetime]` | No | `null` | No |
| `link_target` | `Optional[str]` | No | `null` | No |

Synthetic representation:

```json
{
  "file_type": {},
  "gid": null,
  "link_target": null,
  "mode": null,
  "modified_at": null,
  "name": "example",
  "path": "/remote/example",
  "size": null,
  "uid": null
}
```

<!-- api-model: RemoveConnectionFromGroupRequest -->
## `RemoveConnectionFromGroupRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Remove one membership of a connection from a group.

**Related methods:** `remove_connection_from_group`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `group_id` | `GroupId` | Yes | — | No |

Synthetic representation:

```json
{
  "connection_id": "production",
  "group_id": {}
}
```

<!-- api-model: RemoveKnownHostEntriesRequest -->
## `RemoveKnownHostEntriesRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Batch removal against one loaded revision of the document.

**Related methods:** `remove_known_host_entries`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `revision` | `str` | Yes | — | No |
| `entry_ids` | `tuple[KnownHostEntryId, ...]` | Yes | — | No |

Synthetic representation:

```json
{
  "entry_ids": [],
  "revision": "example"
}
```

<!-- api-model: RenameGroupRequest -->
## `RenameGroupRequest`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Rename a group.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `group_id` | `str` | Yes | — | No |
| `new_name` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "group_id": "example",
  "new_name": "example"
}
```

<!-- api-model: RenameTagRequest -->
## `RenameTagRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Rename a tag across all connections (case-insensitive, deduplicated).

**Related methods:** `rename_tag`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `old_tag` | `str` | Yes | — | No |
| `new_tag` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "new_tag": {},
  "old_tag": {}
}
```

<!-- api-model: ReorderConnectionRequest -->
## `ReorderConnectionRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Reorder a connection above/below a target within a group or the root.

**Related methods:** `reorder_connection`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `target_connection_id` | `ConnectionId` | Yes | — | No |
| `group_id` | `Optional[GroupId]` | No | `null` | No |
| `position` | `str` | No | `below` | No |

Synthetic representation:

```json
{
  "connection_id": "production",
  "group_id": null,
  "position": "below",
  "target_connection_id": {}
}
```

<!-- api-model: ReplayBounds -->
## `ReplayBounds`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `ReplayBounds` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `earliest_sequence` | `int` | Yes | — | No |
| `latest_sequence` | `int` | Yes | — | No |
| `retained_bytes` | `int` | Yes | — | No |

Synthetic representation:

```json
{
  "earliest_sequence": 0,
  "latest_sequence": 0,
  "retained_bytes": 0
}
```

<!-- api-model: ReplayRequest -->
## `ReplayRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `ReplayRequest` record.

**Related methods:** `replay_terminal`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `session_id` | `SessionId` | Yes | — | No |
| `attachment_id` | `AttachmentId | None` | No | `null` | No |
| `after_sequence` | `int | None` | No | `null` | No |
| `max_bytes` | `int` | No | `1048576` | No |

Synthetic representation:

```json
{
  "after_sequence": null,
  "attachment_id": null,
  "max_bytes": 1048576,
  "session_id": "session-12"
}
```

<!-- api-model: ReplayResult -->
## `ReplayResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `ReplayResult` record.

**Related methods:** `replay_terminal`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `session_id` | `SessionId` | Yes | — | No |
| `first_sequence` | `int` | Yes | — | No |
| `next_sequence` | `int` | Yes | — | No |
| `bounds` | `ReplayBounds` | Yes | — | No |
| `data` | `bytes` | No | `<binary bytes>` | Yes |
| `truncated` | `bool` | No | `false` | No |
| `eof` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "bounds": {
    "earliest_sequence": 0,
    "latest_sequence": 0,
    "retained_bytes": 0
  },
  "data": "<sensitive value omitted>",
  "eof": false,
  "first_sequence": 0,
  "next_sequence": 1,
  "session_id": "session-12",
  "truncated": false
}
```

<!-- api-model: RequestEnvelope -->
## `RequestEnvelope`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** One explicitly named daemon method invocation.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `protocol_version` | `str` | Yes | — | No |
| `request_id` | `RequestId` | Yes | — | No |
| `method` | `str` | Yes | — | No |
| `params` | `Mapping[str, Any]` | No | `{}` | Yes |
| `client_id` | `ClientId` | No | `client:unknown` | No |

Synthetic representation:

```json
{
  "client_id": "client:unknown",
  "method": {},
  "params": "<sensitive value omitted>",
  "protocol_version": {},
  "request_id": "request-3"
}
```

<!-- api-model: ResizeTerminalRequest -->
## `ResizeTerminalRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `ResizeTerminalRequest` record.

**Related methods:** `resize_terminal`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `session_id` | `SessionId` | Yes | — | No |
| `attachment_id` | `AttachmentId` | Yes | — | No |
| `dimensions` | `TerminalDimensions` | Yes | — | No |

Synthetic representation:

```json
{
  "attachment_id": "attachment-2",
  "dimensions": {
    "columns": 80,
    "rows": 24
  },
  "session_id": "session-12"
}
```

<!-- api-model: RestartDaemonRequest -->
## `RestartDaemonRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `RestartDaemonRequest` record.

**Related methods:** `restart_daemon`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `force` | `bool` | No | `false` | No |
| `confirmation` | `Optional[str]` | No | `null` | No |

Synthetic representation:

```json
{
  "confirmation": null,
  "force": false
}
```

<!-- api-model: SaveSshConfigTextRequest -->
## `SaveSshConfigTextRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Optimistic raw-text replacement of the daemon-selected SSH config.

``expected_revision`` is the revision returned by the preceding load;
the daemon rejects the save when any participating config file changed
since the editor loaded it.

**Related methods:** `save_ssh_config_text`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `text` | `str` | Yes | — | Yes |
| `expected_revision` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "expected_revision": "example",
  "text": "<sensitive value omitted>"
}
```

<!-- api-model: ServiceFailure -->
## `ServiceFailure`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-safe failure payload for extended SSH services.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `code` | `str` | Yes | — | No |
| `message` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "code": {},
  "message": "Example request"
}
```

<!-- api-model: SessionCapabilities -->
## `SessionCapabilities`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `SessionCapabilities` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `supported` | `frozenset[str]` | No | `[]` | No |

Synthetic representation:

```json
{
  "supported": []
}
```

<!-- api-model: SessionExitInfo -->
## `SessionExitInfo`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `SessionExitInfo` record.

**Related methods:** None
**Related events:** `session.exited`

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `exit_code` | `int | None` | No | `null` | No |
| `signal` | `int | None` | No | `null` | No |
| `reason` | `str` | No | `` | No |

Synthetic representation:

```json
{
  "exit_code": null,
  "reason": "",
  "signal": null
}
```

<!-- api-model: SessionFailure -->
## `SessionFailure`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `SessionFailure` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `code` | `str` | Yes | — | No |
| `message` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "code": "example",
  "message": "Example request"
}
```

<!-- api-model: SessionSummary -->
## `SessionSummary`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `SessionSummary` record.

**Related methods:** `attach_session`, `get_session`, `list_sessions`, `open_session`
**Related events:** `session.created`, `session.state_changed`, `session.closed`

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `id` | `SessionId` | Yes | — | No |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `state` | `SessionState` | Yes | — | No |
| `created_at` | `datetime` | No | `<UTC timestamp at creation>` | No |
| `input_owner` | `InputOwner | None` | No | `null` | No |
| `capabilities` | `SessionCapabilities` | No | `{"supported": []}` | No |
| `exit_info` | `SessionExitInfo | None` | No | `null` | No |
| `failure` | `SessionFailure | None` | No | `null` | No |
| `attachment_count` | `int` | No | `0` | No |

Synthetic representation:

```json
{
  "attachment_count": 0,
  "capabilities": {
    "supported": []
  },
  "connection_id": "production",
  "created_at": "<UTC timestamp at creation>",
  "exit_info": null,
  "failure": null,
  "id": "production",
  "input_owner": null,
  "state": "created"
}
```

<!-- api-model: SetDaemonLogLevelRequest -->
## `SetDaemonLogLevelRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Typed control request for the daemon's managed logging handlers.

**Related methods:** `set_daemon_log_level`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `level` | `DaemonLogLevel` | Yes | — | No |

Synthetic representation:

```json
{
  "level": {}
}
```

<!-- api-model: SetGroupColorRequest -->
## `SetGroupColorRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Set a group's display color.

**Related methods:** `set_group_color`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `group_id` | `GroupId` | Yes | — | No |
| `color` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "color": {},
  "group_id": {}
}
```

<!-- api-model: SetOperationModeRequest -->
## `SetOperationModeRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Request a serialized, live SSH configuration-scope transition.

**Related methods:** `set_operation_mode`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `mode` | `OperationMode` | Yes | — | No |
| `seed_isolated_config` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "mode": {},
  "seed_isolated_config": false
}
```

<!-- api-model: SetSessionConnectionPasswordRequest -->
## `SetSessionConnectionPasswordRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Identify a daemon-memory-only password supplied in a protected frame.

**Related methods:** `clear_session_connection_password`, `set_session_connection_password`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |

Synthetic representation:

```json
{
  "connection_id": "production"
}
```

<!-- api-model: SftpChmodRequest -->
## `SftpChmodRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `SftpChmodRequest` record.

**Related methods:** `sftp_chmod`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `service_id` | `SftpServiceId` | Yes | — | No |
| `path` | `str` | Yes | — | No |
| `mode` | `int` | Yes | — | No |

Synthetic representation:

```json
{
  "mode": {},
  "path": "/remote/example",
  "service_id": {}
}
```

<!-- api-model: SftpCopyRequest -->
## `SftpCopyRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Copy or move a remote SFTP path within one service.

**Related methods:** `sftp_copy`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `service_id` | `SftpServiceId` | Yes | — | No |
| `source_path` | `str` | Yes | — | No |
| `destination_path` | `str` | Yes | — | No |
| `recursive` | `bool` | No | `false` | No |
| `move` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "destination_path": {},
  "move": false,
  "recursive": false,
  "service_id": {},
  "source_path": {}
}
```

<!-- api-model: SftpCreateFileRequest -->
## `SftpCreateFileRequest`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Create an empty remote file within one SFTP service.

The daemon owns the create: no frontend temporary file or fake upload is
involved, and already-exists / permission / path failures surface as
structured errors.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `service_id` | `SftpServiceId` | Yes | — | No |
| `path` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "path": "/remote/example",
  "service_id": {}
}
```

<!-- api-model: SftpCreateFileResult -->
## `SftpCreateFileResult`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `SftpCreateFileResult` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `path` | `str` | Yes | — | No |
| `mode` | `int` | No | `420` | No |

Synthetic representation:

```json
{
  "mode": 420,
  "path": "/remote/example"
}
```

<!-- api-model: SftpDirectorySizeRequest -->
## `SftpDirectorySizeRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Summarise a remote directory tree within one SFTP service.

**Related methods:** `sftp_directory_size`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `service_id` | `SftpServiceId` | Yes | — | No |
| `path` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "path": "/remote/example",
  "service_id": {}
}
```

<!-- api-model: SftpDirectorySizeResult -->
## `SftpDirectorySizeResult`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `SftpDirectorySizeResult` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `path` | `str` | Yes | — | No |
| `size_bytes` | `int` | Yes | — | No |
| `file_count` | `int` | Yes | — | No |
| `directory_count` | `int` | Yes | — | No |

Synthetic representation:

```json
{
  "directory_count": {},
  "file_count": {},
  "path": "/remote/example",
  "size_bytes": {}
}
```

<!-- api-model: SftpEntry -->
## `SftpEntry`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Legacy schema-compatible SFTP entry; prefer :class:`RemoteFileEntry`.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `name` | `str` | Yes | — | No |
| `path` | `str` | Yes | — | No |
| `kind` | `FileEntryKind` | Yes | — | No |
| `size` | `Optional[int]` | No | `null` | No |

Synthetic representation:

```json
{
  "kind": {},
  "name": "example",
  "path": "/remote/example",
  "size": null
}
```

<!-- api-model: SftpPathRequest -->
## `SftpPathRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `SftpPathRequest` record.

**Related methods:** `sftp_lstat`, `sftp_mkdir`, `sftp_readlink`, `sftp_realpath`, `sftp_remove`, `sftp_rmdir`, `sftp_stat`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `service_id` | `SftpServiceId` | Yes | — | No |
| `path` | `str` | Yes | — | No |
| `recursive` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "path": "/remote/example",
  "recursive": false,
  "service_id": {}
}
```

<!-- api-model: SftpReadFileRequest -->
## `SftpReadFileRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `SftpReadFileRequest` record.

**Related methods:** `sftp_read_file`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `target` | `SftpFileTarget` | Yes | — | No |
| `path` | `str` | Yes | — | No |
| `service_id` | `Optional[SftpServiceId]` | No | `null` | No |
| `access` | `SftpFileAccess` | No | `normal` | No |

Synthetic representation:

```json
{
  "access": "normal",
  "path": "/remote/example",
  "service_id": null,
  "target": {}
}
```

<!-- api-model: SftpReadFileResult -->
## `SftpReadFileResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `SftpReadFileResult` record.

**Related methods:** `sftp_read_file`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `target` | `SftpFileTarget` | Yes | — | No |
| `path` | `str` | Yes | — | No |
| `content` | `str` | Yes | — | Yes |
| `exists` | `bool` | Yes | — | No |
| `revision` | `str` | Yes | — | No |
| `size` | `int` | Yes | — | No |
| `mode` | `Optional[int]` | No | `null` | No |

Synthetic representation:

```json
{
  "content": "<sensitive value omitted>",
  "exists": {},
  "mode": null,
  "path": "/remote/example",
  "revision": {},
  "size": {},
  "target": {}
}
```

<!-- api-model: SftpRenameRequest -->
## `SftpRenameRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `SftpRenameRequest` record.

**Related methods:** `sftp_rename`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `service_id` | `SftpServiceId` | Yes | — | No |
| `source_path` | `str` | Yes | — | No |
| `destination_path` | `str` | Yes | — | No |
| `overwrite` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "destination_path": {},
  "overwrite": false,
  "service_id": {},
  "source_path": {}
}
```

<!-- api-model: SftpReplaceFileRequest -->
## `SftpReplaceFileRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `SftpReplaceFileRequest` record.

**Related methods:** `sftp_replace_file`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `target` | `SftpFileTarget` | Yes | — | No |
| `path` | `str` | Yes | — | No |
| `content` | `str` | Yes | — | Yes |
| `expected_revision` | `str` | Yes | — | No |
| `backup` | `bool` | No | `true` | No |
| `service_id` | `Optional[SftpServiceId]` | No | `null` | No |
| `access` | `SftpFileAccess` | No | `normal` | No |

Synthetic representation:

```json
{
  "access": "normal",
  "backup": true,
  "content": "<sensitive value omitted>",
  "expected_revision": {},
  "path": "/remote/example",
  "service_id": null,
  "target": {}
}
```

<!-- api-model: SftpReplaceFileResult -->
## `SftpReplaceFileResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `SftpReplaceFileResult` record.

**Related methods:** `sftp_replace_file`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `target` | `SftpFileTarget` | Yes | — | No |
| `path` | `str` | Yes | — | No |
| `revision` | `str` | Yes | — | No |
| `size` | `int` | Yes | — | No |
| `backup_path` | `Optional[str]` | No | `null` | No |

Synthetic representation:

```json
{
  "backup_path": null,
  "path": "/remote/example",
  "revision": {},
  "size": {},
  "target": {}
}
```

<!-- api-model: SftpServiceSummary -->
## `SftpServiceSummary`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `SftpServiceSummary` record.

**Related methods:** `attach_sftp`, `get_sftp_service`, `list_sftp_services`, `open_sftp`
**Related events:** `sftp.created`, `sftp.state_changed`, `sftp.closed`, `sftp.failed`

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `id` | `SftpServiceId` | Yes | — | No |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `state` | `SftpServiceState` | Yes | — | No |
| `created_at` | `datetime` | No | `<UTC timestamp at creation>` | No |
| `started_at` | `Optional[datetime]` | No | `null` | No |
| `closed_at` | `Optional[datetime]` | No | `null` | No |
| `attachment_count` | `int` | No | `0` | No |
| `owner_client_id` | `Optional[ClientId]` | No | `null` | No |
| `failure` | `Optional[ServiceFailure]` | No | `null` | No |

Synthetic representation:

```json
{
  "attachment_count": 0,
  "closed_at": null,
  "connection_id": "production",
  "created_at": "<UTC timestamp at creation>",
  "failure": null,
  "id": "production",
  "owner_client_id": null,
  "started_at": null,
  "state": {}
}
```

<!-- api-model: SftpSymlinkRequest -->
## `SftpSymlinkRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `SftpSymlinkRequest` record.

**Related methods:** `sftp_symlink`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `service_id` | `SftpServiceId` | Yes | — | No |
| `target_path` | `str` | Yes | — | No |
| `link_path` | `str` | Yes | — | No |

Synthetic representation:

```json
{
  "link_path": {},
  "service_id": {},
  "target_path": {}
}
```

<!-- api-model: SplitConnectionRequest -->
## `SplitConnectionRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Split a connection out of a multi-host SSH config block.

Removes ``original_host_token`` from the block identified by
``source_config_path`` and appends a new standalone ``Host`` block
built from ``config_patch``.  ``expected_generation`` is reserved
for stale-editor detection: ``None`` means no generation supplied
(the check is skipped); zero is a legitimate generation and is
enforced like any other value.

**Related methods:** `split_connection`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `original_host_token` | `str` | Yes | — | No |
| `source_config_path` | `str` | Yes | — | No |
| `nickname` | `str` | Yes | — | No |
| `hostname` | `str | None` | No | `null` | No |
| `username` | `str | None` | No | `null` | No |
| `port` | `int | None` | No | `null` | No |
| `config_patch` | `Mapping[str, Any]` | No | `{}` | No |
| `expected_generation` | `int | None` | No | `null` | No |

Synthetic representation:

```json
{
  "config_patch": {},
  "connection_id": "production",
  "expected_generation": null,
  "hostname": null,
  "nickname": "example",
  "original_host_token": "example",
  "port": null,
  "source_config_path": "example",
  "username": null
}
```

<!-- api-model: SshConfigText -->
## `SshConfigText`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** The daemon-selected active SSH config text plus editor metadata.

The daemon resolves which file is active (normal or isolated mode) and
never accepts a filesystem path from the client. ``display_name`` is the
daemon-computed display label (home-collapsed); ``writable`` reflects
whether the daemon's hardened atomic write path can replace the file.

**Related methods:** `get_ssh_config_text`, `save_ssh_config_text`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `text` | `str` | Yes | — | Yes |
| `revision` | `str` | Yes | — | No |
| `display_name` | `str` | Yes | — | No |
| `writable` | `bool` | Yes | — | No |

Synthetic representation:

```json
{
  "display_name": "example",
  "revision": "example",
  "text": "<sensitive value omitted>",
  "writable": false
}
```

<!-- api-model: StartScpTransferRequest -->
## `StartScpTransferRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `StartScpTransferRequest` record.

**Related methods:** `start_scp_transfer`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `direction` | `TransferDirection` | Yes | — | No |
| `sources` | `Tuple[str, ...]` | Yes | — | No |
| `destination` | `str` | Yes | — | No |
| `conflict_policy` | `TransferConflictPolicy` | No | `overwrite` | No |
| `recursive` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "conflict_policy": "overwrite",
  "connection_id": "production",
  "destination": {},
  "direction": {},
  "recursive": false,
  "sources": {}
}
```

<!-- api-model: StartTransferRequest -->
## `StartTransferRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `StartTransferRequest` record.

**Related methods:** `start_transfer`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `sftp_service_id` | `SftpServiceId` | Yes | — | No |
| `direction` | `TransferDirection` | Yes | — | No |
| `remote_path` | `str` | Yes | — | No |
| `local_path` | `str` | Yes | — | No |
| `conflict_policy` | `TransferConflictPolicy` | No | `fail` | No |
| `recursive` | `bool` | No | `false` | No |
| `local_mode` | `TransferLocalMode` | No | `daemon_path` | No |

Synthetic representation:

```json
{
  "conflict_policy": "fail",
  "connection_id": "production",
  "direction": {},
  "local_mode": "daemon_path",
  "local_path": {},
  "recursive": false,
  "remote_path": {},
  "sftp_service_id": {}
}
```

<!-- api-model: StopDaemonRequest -->
## `StopDaemonRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `StopDaemonRequest` record.

**Related methods:** `stop_daemon`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `force` | `bool` | No | `false` | No |
| `confirmation` | `Optional[str]` | No | `null` | No |

Synthetic representation:

```json
{
  "confirmation": null,
  "force": false
}
```

<!-- api-model: StoreConnectionPasswordRequest -->
## `StoreConnectionPasswordRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Store or update a login password for a connection.

**Related methods:** `store_connection_password`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `password` | `str` | Yes | — | Yes |
| `previous_hostname` | `str` | No | `` | No |
| `previous_host` | `str` | No | `` | No |
| `previous_username` | `str` | No | `` | No |

Synthetic representation:

```json
{
  "connection_id": "production",
  "password": "<sensitive value omitted>",
  "previous_host": "",
  "previous_hostname": "",
  "previous_username": ""
}
```

<!-- api-model: StoreKeyPassphraseRequest -->
## `StoreKeyPassphraseRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Store a key passphrase supplied through a protected interaction.

**Related methods:** `store_key_passphrase`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `key_path` | `str` | Yes | — | No |
| `interaction_scope_id` | `SessionId` | Yes | — | No |

Synthetic representation:

```json
{
  "interaction_scope_id": "session-12",
  "key_path": "example"
}
```

<!-- api-model: StorePluginSecretRequest -->
## `StorePluginSecretRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `StorePluginSecretRequest` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `plugin_id` | `str` | Yes | — | No |
| `key` | `str` | Yes | — | No |
| `value` | `str` | Yes | — | Yes |

Synthetic representation:

```json
{
  "key": "example",
  "plugin_id": "example.plugin",
  "value": "<sensitive value omitted>"
}
```

<!-- api-model: SuccessResponseEnvelope -->
## `SuccessResponseEnvelope`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** A successful response correlated to exactly one request.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `protocol_version` | `str` | Yes | — | No |
| `request_id` | `RequestId` | Yes | — | No |
| `result` | `Any` | Yes | — | Yes |

Synthetic representation:

```json
{
  "protocol_version": {},
  "request_id": "request-3",
  "result": "<sensitive value omitted>"
}
```

<!-- api-model: TerminalDimensions -->
## `TerminalDimensions`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `TerminalDimensions` record.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `rows` | `int` | Yes | — | No |
| `columns` | `int` | Yes | — | No |

Synthetic representation:

```json
{
  "columns": 80,
  "rows": 24
}
```

<!-- api-model: TerminalInput -->
## `TerminalInput`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `TerminalInput` record.

**Related methods:** `send_terminal_input`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `session_id` | `SessionId` | Yes | — | No |
| `attachment_id` | `AttachmentId` | Yes | — | No |
| `data` | `bytes` | Yes | — | Yes |

Synthetic representation:

```json
{
  "attachment_id": "attachment-2",
  "data": "<sensitive value omitted>",
  "session_id": "session-12"
}
```

<!-- api-model: TerminalOutput -->
## `TerminalOutput`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `TerminalOutput` record.

**Related methods:** None
**Related events:** `session.output`

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `session_id` | `SessionId` | Yes | — | No |
| `sequence` | `int` | Yes | — | No |
| `data` | `bytes` | Yes | — | Yes |
| `created_at` | `datetime` | No | `<UTC timestamp at creation>` | No |
| `replay` | `bool` | No | `false` | No |
| `eof` | `bool` | No | `false` | No |

Synthetic representation:

```json
{
  "created_at": "<UTC timestamp at creation>",
  "data": "<sensitive value omitted>",
  "eof": false,
  "replay": false,
  "sequence": 0,
  "session_id": "session-12"
}
```

<!-- api-model: TransferSummary -->
## `TransferSummary`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Frontend-neutral `TransferSummary` record.

**Related methods:** `get_transfer`, `list_transfers`, `start_scp_transfer`, `start_transfer`
**Related events:** `transfer.created`, `transfer.started`, `transfer.progress`, `transfer.item_completed`, `transfer.completed`, `transfer.cancelled`, `transfer.failed`

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `id` | `TransferId` | Yes | — | No |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `sftp_service_id` | `Optional[SftpServiceId]` | Yes | — | No |
| `direction` | `TransferDirection` | Yes | — | No |
| `state` | `TransferState` | Yes | — | No |
| `source_display` | `str` | Yes | — | No |
| `destination_display` | `str` | Yes | — | No |
| `backend` | `TransferBackend` | No | `sftp` | No |
| `bytes_total` | `Optional[int]` | No | `null` | No |
| `bytes_completed` | `int` | No | `0` | No |
| `created_at` | `datetime` | No | `<UTC timestamp at creation>` | No |
| `started_at` | `Optional[datetime]` | No | `null` | No |
| `completed_at` | `Optional[datetime]` | No | `null` | No |
| `owner_client_id` | `Optional[ClientId]` | No | `null` | No |
| `failure` | `Optional[ServiceFailure]` | No | `null` | No |
| `bytes_transferred` | `Optional[int]` | No | `null` | No |
| `total_bytes` | `Optional[int]` | No | `null` | No |

Synthetic representation:

```json
{
  "backend": "sftp",
  "bytes_completed": 0,
  "bytes_total": null,
  "bytes_transferred": null,
  "completed_at": null,
  "connection_id": "production",
  "created_at": "<UTC timestamp at creation>",
  "destination_display": {},
  "direction": {},
  "failure": null,
  "id": "production",
  "owner_client_id": null,
  "sftp_service_id": {},
  "source_display": {},
  "started_at": null,
  "state": {},
  "total_bytes": null
}
```

<!-- api-model: UnsavedHostCheckRequest -->
## `UnsavedHostCheckRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Semantic destination facts for daemon-owned save-prompt detection.

**Related methods:** `check_unsaved_host`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `hostname` | `str` | Yes | — | No |
| `username` | `str` | No | `` | No |
| `connection_id` | `str | None` | No | `null` | No |
| `port` | `int | None` | No | `null` | No |
| `protocol` | `str` | No | `ssh` | No |
| `proxy_jump` | `tuple[str, ...]` | No | `[]` | No |

Synthetic representation:

```json
{
  "connection_id": null,
  "hostname": "example.invalid",
  "port": null,
  "protocol": "ssh",
  "proxy_jump": [],
  "username": ""
}
```

<!-- api-model: UnsavedHostCheckResult -->
## `UnsavedHostCheckResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Authoritative result for whether a destination is already saved.

**Related methods:** `check_unsaved_host`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `saved` | `bool` | Yes | — | No |
| `hostname` | `str` | Yes | — | No |
| `username` | `str` | Yes | — | No |
| `generation` | `int` | Yes | — | No |

Synthetic representation:

```json
{
  "generation": 0,
  "hostname": "example.invalid",
  "saved": false,
  "username": "user"
}
```

<!-- api-model: UpdateConnectionMetadataRequest -->
## `UpdateConnectionMetadataRequest`

**Status:** Schema only
**Introduced:** Protocol v1
**Purpose:** Update non-SSH metadata (tags, WoL settings) for a connection.

**Related methods:** None
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `connection_id` | `ConnectionId` | Yes | — | No |
| `meta` | `Mapping[str, Any]` | Yes | — | No |

Synthetic representation:

```json
{
  "connection_id": "production",
  "meta": {}
}
```

<!-- api-model: UpdateConnectionRequest -->
## `UpdateConnectionRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Patch a connection's configuration.

Core identity fields use ``None`` = preserve (backward-compatible).
Newer fields use ``UNSET`` = preserve, ``""`` = clear, value = apply.

``config_patch`` is a presence-aware dict: keys present in the dict
are applied; absent keys are preserved.  The codec builds this from
explicitly present keys in the incoming JSON — omission means preserve.

``expected_generation`` guards stale editors: ``None`` means no
generation supplied (the check is skipped); zero is a legitimate
first-generation value and is enforced like any other.

**Related methods:** `update_connection`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `nickname` | `str | None | UNSET` | No | ``UNSET`` | No |
| `hostname` | `str | None | UNSET` | No | ``UNSET`` | No |
| `username` | `str | None | UNSET` | No | ``UNSET`` | No |
| `port` | `int | None | UNSET` | No | ``UNSET`` | No |
| `display_name` | `str | None | UNSET` | No | ``UNSET`` | No |
| `config_patch` | `Mapping[str, Any]` | No | `{}` | No |
| `plugin_data` | `Mapping[str, Any]` | No | `{}` | No |
| `expected_generation` | `int | None` | No | `null` | No |

Synthetic representation:

```json
{
  "config_patch": {},
  "display_name": "`UNSET`",
  "expected_generation": null,
  "hostname": "`UNSET`",
  "nickname": "`UNSET`",
  "plugin_data": {},
  "port": "`UNSET`",
  "username": "`UNSET`"
}
```

<!-- api-model: VerifyKeyPassphraseRequest -->
## `VerifyKeyPassphraseRequest`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Request daemon-owned verification using a protected interaction secret.

**Related methods:** `verify_key_passphrase`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `key_path` | `str` | Yes | — | No |
| `interaction_scope_id` | `SessionId` | Yes | — | No |

Synthetic representation:

```json
{
  "interaction_scope_id": {},
  "key_path": {}
}
```

<!-- api-model: VerifyKeyPassphraseResult -->
## `VerifyKeyPassphraseResult`

**Status:** Implemented
**Introduced:** Protocol v1
**Purpose:** Whether the protected passphrase unlocked the selected private key.

**Related methods:** `verify_key_passphrase`
**Related events:** None

| Field | Type | Required | Default | Sensitive |
| --- | --- | ---: | --- | ---: |
| `valid` | `bool` | Yes | — | No |

Synthetic representation:

```json
{
  "valid": {}
}
```
