agentmux_srv\backend/

rpc_types.rs

#![allow(dead_code)]
// Copyright 2025-2026, AgentMux Corp.
// SPDX-License-Identifier: Apache-2.0

//! RPC wire format types: Rust equivalents of Go structs from
//! pkg/wshutil/wshrpc.go and pkg/wshrpc/wshrpctypes.go.


use std::collections::HashMap;

use serde::{Deserialize, Serialize};

use super::oref::ORef;
use super::obj::{Block, MetaMapType, Workspace};

// ---- RpcMessage wire format ----

/// Matches Go's `wshutil.RpcMessage` from pkg/wshutil/wshrpc.go.
/// This is the on-the-wire JSON envelope for all RPC communication.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct RpcMessage {
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub command: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub reqid: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub resid: String,
    #[serde(default, skip_serializing_if = "is_zero_i64")]
    pub timeout: i64,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub route: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub authtoken: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub source: String,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub cont: bool,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub cancel: bool,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub error: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub datatype: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub data: Option<serde_json::Value>,
}

impl RpcMessage {
    pub fn is_rpc_request(&self) -> bool {
        !self.command.is_empty() || !self.reqid.is_empty()
    }

    /// Validates the packet structure. Matches Go's `RpcMessage.Validate()`.
    pub fn validate(&self) -> Result<(), String> {
        if !self.reqid.is_empty() && !self.resid.is_empty() {
            return Err("request packets may not have both reqid and resid set".into());
        }
        if self.cancel {
            if !self.command.is_empty() {
                return Err("cancel packets may not have command set".into());
            }
            if self.reqid.is_empty() && self.resid.is_empty() {
                return Err("cancel packets must have reqid or resid set".into());
            }
            if self.data.is_some() {
                return Err("cancel packets may not have data set".into());
            }
            return Ok(());
        }
        if !self.command.is_empty() {
            if !self.resid.is_empty() {
                return Err("command packets may not have resid set".into());
            }
            if !self.error.is_empty() {
                return Err("command packets may not have error set".into());
            }
            if !self.datatype.is_empty() {
                return Err("command packets may not have datatype set".into());
            }
            return Ok(());
        }
        if !self.reqid.is_empty() {
            if self.resid.is_empty() {
                return Err("request packets must have resid set".into());
            }
            if self.timeout != 0 {
                return Err("non-command request packets may not have timeout set".into());
            }
            return Ok(());
        }
        if !self.resid.is_empty() {
            if !self.command.is_empty() {
                return Err("response packets may not have command set".into());
            }
            if self.reqid.is_empty() {
                return Err("response packets must have reqid set".into());
            }
            if self.timeout != 0 {
                return Err("response packets may not have timeout set".into());
            }
            return Ok(());
        }
        Err("invalid packet: must have command, reqid, or resid set".into())
    }
}

// ---- Size/type constants (match Go) ----

pub const MAX_FILE_SIZE: usize = 50 * 1024 * 1024; // 50M
pub const MAX_DIR_SIZE: usize = 1024;
pub const FILE_CHUNK_SIZE: usize = 64 * 1024;
pub const DIR_CHUNK_SIZE: usize = 128;

pub const LOCAL_CONN_NAME: &str = "local";

// ---- RPC type constants ----

pub const RPC_TYPE_CALL: &str = "call";
pub const RPC_TYPE_RESPONSE_STREAM: &str = "responsestream";
pub const RPC_TYPE_STREAMING_REQUEST: &str = "streamingrequest";
pub const RPC_TYPE_COMPLEX: &str = "complex";

// ---- CreateBlock action constants ----

pub const CREATE_BLOCK_ACTION_REPLACE: &str = "replace";
pub const CREATE_BLOCK_ACTION_SPLIT_UP: &str = "splitup";
pub const CREATE_BLOCK_ACTION_SPLIT_DOWN: &str = "splitdown";
pub const CREATE_BLOCK_ACTION_SPLIT_LEFT: &str = "splitleft";
pub const CREATE_BLOCK_ACTION_SPLIT_RIGHT: &str = "splitright";

// ---- Command constants (match Go's wshrpc.Command_* constants) ----

// Special commands
pub const COMMAND_AUTHENTICATE: &str = "authenticate";
pub const COMMAND_AUTHENTICATE_TOKEN: &str = "authenticatetoken";
pub const COMMAND_DISPOSE: &str = "dispose";
pub const COMMAND_ROUTE_ANNOUNCE: &str = "routeannounce";
pub const COMMAND_ROUTE_UNANNOUNCE: &str = "routeunannounce";

// Core commands
pub const COMMAND_MESSAGE: &str = "message";
pub const COMMAND_GET_META: &str = "getmeta";
pub const COMMAND_SET_META: &str = "setmeta";
pub const COMMAND_SET_VIEW: &str = "setview";

// Controller commands
pub const COMMAND_CONTROLLER_INPUT: &str = "controllerinput";
pub const COMMAND_CONTROLLER_RESTART: &str = "controllerrestart";
pub const COMMAND_CONTROLLER_STOP: &str = "controllerstop";
pub const COMMAND_CONTROLLER_RESYNC: &str = "controllerresync";

/// Per-tool-call permission decision RPC. Frontend sends after the
/// user clicks Allow / Deny in `AgentDecisionPanel`. Today the
/// handler validates the payload and logs the decision (audit
/// trail); actual delivery to the agent CLI — rules persistence
/// vs. interactive subprocess — is deferred to PR-3b/PR-4 per
/// docs/specs/SPEC_DECISION_PROMPT_2026_04_24.md §9.1.
pub const COMMAND_TOOL_DECISION: &str = "tooldecision";

// Subprocess agent commands
pub const COMMAND_SUBPROCESS_SPAWN: &str = "subprocessspawn";
pub const COMMAND_AGENT_INPUT: &str = "agentinput";
pub const COMMAND_AGENT_STOP: &str = "agentstop";
pub const COMMAND_WRITE_AGENT_CONFIG: &str = "writeagentconfig";
pub const COMMAND_RESOLVE_CLI: &str = "resolvecli";
pub const COMMAND_CHECK_CLI_AUTH: &str = "checkcliauth";

// Block commands
pub const COMMAND_MKDIR: &str = "mkdir";
pub const COMMAND_RESOLVE_IDS: &str = "resolveids";
pub const COMMAND_BLOCK_INFO: &str = "blockinfo";
pub const COMMAND_BLOCKS_LIST: &str = "blockslist";
pub const COMMAND_CREATE_BLOCK: &str = "createblock";
pub const COMMAND_DELETE_BLOCK: &str = "deleteblock";

// File commands
pub const COMMAND_FILE_WRITE: &str = "filewrite";
pub const COMMAND_FILE_READ: &str = "fileread";
pub const COMMAND_FILE_READ_STREAM: &str = "filereadstream";
pub const COMMAND_FILE_MOVE: &str = "filemove";
pub const COMMAND_FILE_COPY: &str = "filecopy";
pub const COMMAND_FILE_STREAM_TAR: &str = "filestreamtar";
pub const COMMAND_FILE_APPEND: &str = "fileappend";
pub const COMMAND_FILE_APPEND_IJSON: &str = "fileappendijson";
pub const COMMAND_FILE_JOIN: &str = "filejoin";
pub const COMMAND_FILE_SHARE_CAPABILITY: &str = "filesharecapability";

// Event commands
pub const COMMAND_EVENT_PUBLISH: &str = "eventpublish";
pub const COMMAND_EVENT_RECV: &str = "eventrecv";
pub const COMMAND_EVENT_SUB: &str = "eventsub";
pub const COMMAND_EVENT_UNSUB: &str = "eventunsub";
pub const COMMAND_EVENT_UNSUB_ALL: &str = "eventunsuball";
pub const COMMAND_EVENT_READ_HISTORY: &str = "eventreadhistory";

// Stream/test commands
pub const COMMAND_STREAM_TEST: &str = "streamtest";
pub const COMMAND_STREAM_CPU_DATA: &str = "streamcpudata";
pub const COMMAND_TEST: &str = "test";

// Config commands
pub const COMMAND_SET_CONFIG: &str = "setconfig";
pub const COMMAND_SET_CONNECTIONS_CONFIG: &str = "connectionsconfig";
pub const COMMAND_GET_FULL_CONFIG: &str = "getfullconfig";

// Remote commands
pub const COMMAND_REMOTE_STREAM_FILE: &str = "remotestreamfile";
pub const COMMAND_REMOTE_TAR_STREAM: &str = "remotetarstream";
pub const COMMAND_REMOTE_FILE_INFO: &str = "remotefileinfo";
pub const COMMAND_REMOTE_FILE_TOUCH: &str = "remotefiletouch";
pub const COMMAND_REMOTE_WRITE_FILE: &str = "remotewritefile";
pub const COMMAND_REMOTE_FILE_DELETE: &str = "remotefiledelete";
pub const COMMAND_REMOTE_FILE_JOIN: &str = "remotefilejoin";
pub const COMMAND_REMOTE_MKDIR: &str = "remotemkdir";
pub const COMMAND_REMOTE_GET_INFO: &str = "remotegetinfo";
pub const COMMAND_REMOTE_INSTALL_RC_FILES: &str = "remoteinstallrcfiles";

// Info/activity commands
pub const COMMAND_APP_INFO: &str = "waveinfo";
pub const COMMAND_ACTIVITY: &str = "activity";
pub const COMMAND_GET_VAR: &str = "getvar";
pub const COMMAND_SET_VAR: &str = "setvar";

// Connection commands
pub const COMMAND_CONN_STATUS: &str = "connstatus";
pub const COMMAND_WSL_STATUS: &str = "wslstatus";
pub const COMMAND_CONN_ENSURE: &str = "connensure";
pub const COMMAND_CONN_CONNECT: &str = "connconnect";
pub const COMMAND_CONN_DISCONNECT: &str = "conndisconnect";
pub const COMMAND_CONN_LIST: &str = "connlist";
pub const COMMAND_CONN_LIST_AWS: &str = "connlistaws";
pub const COMMAND_WSL_LIST: &str = "wsllist";
pub const COMMAND_WSL_DEFAULT_DISTRO: &str = "wsldefaultdistro";
// COMMAND_CONN_REINSTALL_WSH / COMMAND_CONN_UPDATE_WSH / COMMAND_DISMISS_WSH_FAIL
// have been removed — wsh has been retired. See
// specs/SPEC_RETIRE_WSH_2026_04_12.md.

// Workspace commands
pub const COMMAND_WORKSPACE_LIST: &str = "workspacelist";

// UI commands
pub const COMMAND_WEB_SELECTOR: &str = "webselector";
pub const COMMAND_NOTIFY: &str = "notify";
pub const COMMAND_FOCUS_WINDOW: &str = "focuswindow";
pub const COMMAND_GET_UPDATE_CHANNEL: &str = "getupdatechannel";

// VDom commands
pub const COMMAND_VDOM_CREATE_CONTEXT: &str = "vdomcreatecontext";
pub const COMMAND_VDOM_ASYNC_INITIATION: &str = "vdomasyncinitiation";
pub const COMMAND_VDOM_RENDER: &str = "vdomrender";
pub const COMMAND_VDOM_URL_REQUEST: &str = "vdomurlrequest";

// AI commands
pub const COMMAND_AI_SEND_MESSAGE: &str = "aisendmessage";
pub const COMMAND_GET_AI_RATE_LIMIT: &str = "getwaveairatelimit";

// Screenshot
pub const COMMAND_CAPTURE_BLOCK_SCREENSHOT: &str = "captureblockscreenshot";

// RT info
pub const COMMAND_GET_RT_INFO: &str = "getrtinfo";
pub const COMMAND_SET_RT_INFO: &str = "setrtinfo";

// Terminal
pub const COMMAND_TERM_GET_SCROLLBACK_LINES: &str = "termgetscrollbacklines";

// Agent
pub const COMMAND_LIST_AGENTS: &str = "listagents";
pub const COMMAND_CREATE_AGENT: &str = "createagent";
pub const COMMAND_UPDATE_AGENT: &str = "updateagent";
pub const COMMAND_DELETE_AGENT: &str = "deleteagent";
pub const COMMAND_GET_AGENT_CONTENT: &str = "getagentcontent";
pub const COMMAND_SET_AGENT_CONTENT: &str = "setagentcontent";
pub const COMMAND_GET_ALL_AGENT_CONTENT: &str = "getallagentcontent";

// Agent Skills
pub const COMMAND_LIST_AGENT_SKILLS: &str = "listagentskills";
pub const COMMAND_CREATE_AGENT_SKILL: &str = "createagentskill";
pub const COMMAND_UPDATE_AGENT_SKILL: &str = "updateagentskill";
pub const COMMAND_DELETE_AGENT_SKILL: &str = "deleteagentskill";

// Agent History
pub const COMMAND_APPEND_AGENT_HISTORY: &str = "appendagenthistory";
pub const COMMAND_LIST_AGENT_HISTORY: &str = "listagenthistory";
pub const COMMAND_SEARCH_AGENT_HISTORY: &str = "searchagenthistory";

// Agent Import
pub const COMMAND_IMPORT_AGENT_FROM_CLAW: &str = "importagentfromclaw";
pub const COMMAND_IMPORT_AGENTS: &str = "importagents";

// Agent Export
pub const COMMAND_EXPORT_AGENTS: &str = "exportagents";

// Agent Seed
pub const COMMAND_RESEED_AGENTS: &str = "reseedagents";

// Identity accounts (v6 — replaces localStorage)
pub const COMMAND_LIST_IDENTITY_ACCOUNTS: &str = "listidentityaccounts";
pub const COMMAND_GET_IDENTITY_ACCOUNT: &str = "getidentityaccount";
pub const COMMAND_UPSERT_IDENTITY_ACCOUNT: &str = "upsertidentityaccount";
pub const COMMAND_DELETE_IDENTITY_ACCOUNT: &str = "deleteidentityaccount";

// Agent ↔ Identity junction
pub const COMMAND_LINK_AGENT_IDENTITY: &str = "linkagentidentity";
pub const COMMAND_UNLINK_AGENT_IDENTITY: &str = "unlinkagentidentity";
pub const COMMAND_LIST_AGENT_IDENTITIES: &str = "listagentidentities";

// Identity bundles (v7 — named credential bundles)
pub const COMMAND_LIST_IDENTITY_BUNDLES: &str = "listidentitybundles";
pub const COMMAND_GET_IDENTITY_BUNDLE: &str = "getidentitybundle";
pub const COMMAND_UPSERT_IDENTITY_BUNDLE: &str = "upsertidentitybundle";
pub const COMMAND_DELETE_IDENTITY_BUNDLE: &str = "deleteidentitybundle";
pub const COMMAND_BIND_IDENTITY_ACCOUNT: &str = "bindidentityaccount";
pub const COMMAND_UNBIND_IDENTITY_ACCOUNT: &str = "unbindidentityaccount";
pub const COMMAND_LIST_IDENTITY_BINDINGS: &str = "listidentitybindings";

// Memory bundles (v7 — agent personality / capability stack)
pub const COMMAND_LIST_MEMORIES: &str = "listmemories";
pub const COMMAND_GET_MEMORY: &str = "getmemory";
pub const COMMAND_UPSERT_MEMORY: &str = "upsertmemory";
pub const COMMAND_DELETE_MEMORY: &str = "deletememory";

// Agent instances
pub const COMMAND_LIST_AGENT_INSTANCES: &str = "listagentinstances";
pub const COMMAND_GET_AGENT_INSTANCE: &str = "getagentinstance";
pub const COMMAND_CREATE_AGENT_INSTANCE: &str = "createagentinstance";
pub const COMMAND_UPDATE_AGENT_INSTANCE: &str = "updateagentinstance";
pub const COMMAND_DELETE_AGENT_INSTANCE: &str = "deleteagentinstance";
/// v8 — list named agent instances for the launch modal's "Continue
/// agent" dropdown. Filters to non-hidden rows with a non-empty
/// instance_name, joined with definition + identity + memory bundles.
pub const COMMAND_LIST_NAMED_AGENTS: &str = "listnamedagents";
/// v8 — soft-delete (hide) a named agent instance from the dropdown.
/// Row + working directory remain on disk for audit + recovery.
pub const COMMAND_HIDE_NAMED_AGENT: &str = "hidenamedagent";
/// Cascade follow-up (2026-05-23) — list recent agent sessions with
/// conversation previews extracted from the filestore `output.state.json`
/// snapshot. Powers the AgentPicker's "Recent sessions" surface so a
/// pane crash that orphans a conversation becomes recoverable from
/// normal UI. See `docs/recovery/MAKS_CONVERSATION_2026_05_23.md`.
pub const COMMAND_LIST_RECENT_SESSIONS: &str = "listrecentsessions";

// Agent definition branching
pub const COMMAND_FORK_AGENT_DEFINITION: &str = "forkagentdefinition";

/// Two-tier picker (Phase 1 — SPEC_AGENT_PICKER_TWO_TIER_2026_05_24.md).
/// Clone a seeded template into a new user-owned agent definition with
/// `is_seeded = 0`. Copies provider + cmd + env + auth-config fields
/// from the template, applies the caller-supplied name + bindings,
/// returns the new definition_id so the frontend can immediately
/// launch. Rejects non-template ids + duplicate user-agent names.
pub const COMMAND_AGENT_DEF_CREATE_FROM_TEMPLATE: &str = "agentdefcreatefromtemplate";

/// Two-tier picker (Phase 2 — SPEC_AGENT_PICKER_TWO_TIER_2026_05_24.md
/// Q2 Decision Y). Set the `user_hidden` flag on a seeded template so
/// it disappears from the default `+ New from template` list. Idempotent;
/// rejects user-owned (`is_seeded = 0`) definitions — those use
/// `deleteagent` instead. Manifest re-sync resets `user_hidden = 0` for
/// any newly-added template id so fresh templates always surface once.
pub const COMMAND_AGENT_DEF_HIDE: &str = "agentdefhide";
/// Two-tier picker (Phase 2). Inverse of `agentdefhide` — set
/// `user_hidden = 0` so a previously-hidden template reappears in the
/// picker's templates tier. Powers the settings "Hidden templates"
/// unhide affordance. Same validation as hide.
pub const COMMAND_AGENT_DEF_UNHIDE: &str = "agentdefunhide";
/// Two-tier picker (Phase 2). Return only the hidden templates
/// (`is_seeded = 1 AND user_hidden = 1`). Backs the settings UI's
/// list of templates the user can unhide. The picker proper never
/// calls this — it uses `listagents` (which excludes hidden rows
/// by default).
pub const COMMAND_AGENT_DEF_LIST_HIDDEN_TEMPLATES: &str = "agentdeflisthiddentemplates";

// Drone pane (v8 — issue #753 Phase 1)
pub const COMMAND_LIST_DRONES: &str = "listdrones";
pub const COMMAND_GET_DRONE: &str = "getdrone";
pub const COMMAND_UPSERT_DRONE: &str = "upsertdrone";
pub const COMMAND_DELETE_DRONE: &str = "deletedrone";
pub const COMMAND_RUN_DRONE: &str = "rundrone";
pub const COMMAND_LIST_DRONE_RUNS: &str = "listdroneruns";

// App API Tier 1 — agent lifecycle commands
pub const COMMAND_AGENT_OPEN: &str = "agent.open";
pub const COMMAND_AGENT_SEND: &str = "agent.send";
pub const COMMAND_AGENT_STOP_API: &str = "agent.stop";
pub const COMMAND_AGENT_STATUS: &str = "agent.status";
pub const COMMAND_AGENT_LIST: &str = "agent.list";
pub const COMMAND_AGENT_OUTPUT: &str = "agent.output";
pub const COMMAND_AGENT_STREAM: &str = "agent.stream";
/// List every OS process currently tracked for a given agent block.
/// Returns `AgentProcessListResult`. Consumed by the swarm activity
/// panel. See `backend::process_tracker`.
pub const COMMAND_AGENT_PROCESS_LIST: &str = "agent.process-list";
/// List every block currently tracked (for the swarm aggregate view).
/// Returns `AgentTrackedBlocksResult`.
pub const COMMAND_AGENT_TRACKED_BLOCKS: &str = "agent.tracked-blocks";
/// Terminate a single process by PID if it's a member of a given
/// block's tracker tree. Silently no-ops if the PID isn't tracked.
/// Returns `AgentKillResult { ok: bool }`.
pub const COMMAND_AGENT_KILL_PROCESS: &str = "agent.kill-process";
/// Terminate the entire process tree for a given block.
/// On Windows: `TerminateJobObject`. On Linux: `cgroup.kill`. On
/// macOS: `killpg`. Returns `AgentKillResult { ok: true }` even when
/// there are no members (idempotent).
pub const COMMAND_AGENT_KILL_TREE: &str = "agent.kill-tree";

// App API Tier 2 — pane lifecycle commands
pub const COMMAND_PANE_OPEN: &str = "pane.open";

// App API Tier 1 — blockfile pagination commands
pub const COMMAND_BLOCKFILE_LINE_COUNT: &str = "blockfile:line_count";
pub const COMMAND_BLOCKFILE_READ_RANGE: &str = "blockfile:read_range";
pub const COMMAND_BLOCKFILE_READ_STATE: &str = "blockfile:read_state";
pub const COMMAND_BLOCKFILE_WRITE_STATE: &str = "blockfile:write_state";

// App API Tier 1 — session archival commands
pub const COMMAND_SESSION_ARCHIVE: &str = "session:archive";
pub const COMMAND_SESSION_RESTORE: &str = "session:restore";
pub const COMMAND_SESSION_EXPORT: &str = "session:export";

// Session digest
pub const COMMAND_SESSION_DIGEST: &str = "session:digest";

// Option E (PR 1 of 2) — agent-anchored session zones.
// A session zone is bound to the *agent definition* (`definition_id`),
// not the identity bundle. Every block of the same agent reads/writes
// through `agent:<defId>:current`; archiving snapshots to
// `agent:<defId>:archive:<ts_ms>`. See
// docs/specs/SPEC_CONTINUATION_SESSION_PERSISTENCE_2026_05_23.md.
pub const COMMAND_AGENT_SESSION_READ: &str = "agent:session:read";
pub const COMMAND_AGENT_SESSION_WRITE_STATE: &str = "agent:session:write_state";
pub const COMMAND_AGENT_SESSION_APPEND_OUTPUT: &str = "agent:session:append_output";
pub const COMMAND_AGENT_SESSION_ARCHIVE: &str = "agent:session:archive";
pub const COMMAND_AGENT_SESSION_LIST_ARCHIVES: &str = "agent:session:list_archives";

// ---- Client type constants ----

pub const CLIENT_TYPE_CONN_SERVER: &str = "connserver";
pub const CLIENT_TYPE_BLOCK_CONTROLLER: &str = "blockcontroller";

// ---- Command data types ----

/// Matches Go's `CommandGetMetaData`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandGetMetaData {
    pub oref: ORef,
}

/// Matches Go's `CommandSetMetaData`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandSetMetaData {
    pub oref: ORef,
    pub meta: MetaMapType,
}

/// Matches Go's `CommandMessageData`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandMessageData {
    #[serde(default)]
    pub oref: ORef,
    pub message: String,
}

/// Matches Go's `CommandAuthenticateRtnData`
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct CommandAuthenticateRtnData {
    pub routeid: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub authtoken: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub env: Option<HashMap<String, String>>,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub initscripttext: String,
}

/// Matches Go's `CommandAuthenticateTokenData`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandAuthenticateTokenData {
    pub token: String,
}

/// Matches Go's `CommandDisposeData`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandDisposeData {
    pub routeid: String,
}

/// Matches Go's `CommandResolveIdsData`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandResolveIdsData {
    #[serde(default)]
    pub blockid: String,
    pub ids: Vec<String>,
}

/// Matches Go's `CommandResolveIdsRtnData`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandResolveIdsRtnData {
    pub resolvedids: HashMap<String, ORef>,
}

/// Matches Go's `CommandCreateBlockData`
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct CommandCreateBlockData {
    #[serde(default)]
    pub tabid: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub blockdef: Option<serde_json::Value>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rtopts: Option<serde_json::Value>,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub magnified: bool,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub ephemeral: bool,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub focused: bool,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub targetblockid: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub targetaction: String,
}

/// Matches Go's `CommandDeleteBlockData`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandDeleteBlockData {
    pub blockid: String,
}

/// Matches Go's `CommandBlockSetViewData`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandBlockSetViewData {
    pub blockid: String,
    pub view: String,
}

/// Matches Go's `CommandControllerResyncData`
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct CommandControllerResyncData {
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub forcerestart: bool,
    #[serde(default)]
    pub tabid: String,
    #[serde(default)]
    pub blockid: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rtopts: Option<serde_json::Value>,
}

/// Matches Go's `CommandBlockInputData`
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct CommandBlockInputData {
    pub blockid: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub inputdata64: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub signame: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub termsize: Option<serde_json::Value>,
    /// Per-TermViewModel monotonic counter for seq-based input ordering (optional, shell only).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub seq: Option<u64>,
}

/// Data for `tooldecision` — frontend's reply to a per-tool-call
/// permission gate. Today the backend validates the outcome and
/// logs the decision; actual delivery to the agent CLI is deferred
/// to PR-3b/PR-4 (rules persistence vs. interactive subprocess
/// path). Spec:
/// docs/specs/SPEC_DECISION_PROMPT_2026_04_24.md §9.1.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct CommandToolDecisionData {
    pub blockid: String,
    /// Opaque id matched against a `PermissionRequestEvent`. Echoed
    /// in the audit log so the audit trail can be cross-referenced.
    pub request_id: String,
    /// "allow" or "deny". Anything else returns an error.
    pub outcome: String,
    /// "once" / "session" / "project" / "global". Captured so the
    /// rules-persistence layer (PR-3b) can write a matching rule
    /// without re-asking the user.
    pub scope: String,
    /// User-typed denial reason. Optional. Future PR will relay
    /// this verbatim into the agent's next prompt.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub feedback: Option<String>,
}

// ---- Subprocess agent command data types ----

/// Data for SubprocessSpawnCommand — spawn agent CLI for a single turn.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandSubprocessSpawnData {
    pub blockid: String,
    pub tabid: String,
    pub cli_command: String,
    #[serde(default)]
    pub cli_args: Vec<String>,
    #[serde(default)]
    pub working_dir: String,
    #[serde(default)]
    pub env_vars: std::collections::HashMap<String, String>,
    /// The user's JSON message to write to subprocess stdin.
    pub message: String,
}

/// Data for AgentInputCommand — send a follow-up message (re-spawns with --resume).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandAgentInputData {
    pub blockid: String,
    /// The user's JSON message string.
    pub message: String,
    /// Optional client-supplied id. Echoed back via the
    /// `agent-message-accepted` event when this message transitions
    /// from queued to running so the frontend can match its pending
    /// `PendingMessage` entry and promote it into the conversation
    /// document. Absent for pre-existing callers; treated as no-id.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub message_id: Option<String>,
}

/// Data for AgentStopCommand — stop the running subprocess.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandAgentStopData {
    pub blockid: String,
    #[serde(default)]
    pub force: bool,
}

/// A file to write as part of agent config.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentConfigFile {
    pub path: String,
    pub content: String,
}

/// Data for WriteAgentConfigCommand — write config files atomically.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandWriteAgentConfigData {
    /// Agent working directory where files are written.
    pub working_dir: String,
    /// Files to write (path relative to working_dir, content).
    pub files: Vec<AgentConfigFile>,
    /// When true, treat `working_dir` as an auto-generated instance
    /// path eligible for `<base>-N` collision resolution. When false
    /// (user-specified `agent.working_directory` like `~/projects/X`),
    /// write into the path as-is — no rewrite, no suffixing. The
    /// frontend sets this based on whether it constructed the path
    /// itself or pulled it from the agent definition.
    #[serde(default)]
    pub auto_allocate: bool,
}

/// Result of WriteAgentConfigCommand. Returns the final working
/// directory used; callers should compare against the requested
/// `working_dir` and patch `cmd:cwd` (via SetMeta) when they differ
/// so the controller spawns the CLI in the actually-created dir.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandWriteAgentConfigResult {
    pub working_dir: String,
}

/// Data for ResolveCliCommand — detect or install a CLI tool.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandResolveCliData {
    /// Provider ID (e.g. "claude", "codex", "gemini")
    pub provider_id: String,
    /// CLI command name (e.g. "claude")
    pub cli_command: String,
    /// npm package name for fallback install (e.g. "@anthropic-ai/claude-code")
    pub npm_package: String,
    /// Version to install ("latest" or specific version)
    pub pinned_version: String,
    /// Windows install command (e.g. "irm https://claude.ai/install.ps1 | iex")
    #[serde(default)]
    pub windows_install_command: String,
    /// Unix install command (e.g. "curl -fsSL https://claude.ai/install.sh | bash")
    #[serde(default)]
    pub unix_install_command: String,
    /// Block ID to stream install output into (optional — if empty, no streaming)
    #[serde(default)]
    pub block_id: String,
}

/// Result from ResolveCliCommand
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ResolveCliResult {
    /// Absolute path to the CLI binary
    pub cli_path: String,
    /// CLI version string
    pub version: String,
    /// How it was resolved: "path", "local_install", "installed"
    pub source: String,
}

/// Data for CheckCliAuthCommand — check if CLI is authenticated.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandCheckCliAuthData {
    /// Absolute path to CLI binary
    pub cli_path: String,
    /// Auth check args (e.g. ["auth", "status", "--json"])
    pub auth_check_args: Vec<String>,
    /// Environment variables to set when running the auth check (e.g. CLAUDE_CONFIG_DIR).
    /// Must match the env vars used when spawning the actual subprocess so the check
    /// reads credentials from the same isolated directory.
    #[serde(default)]
    pub auth_env: std::collections::HashMap<String, String>,
}

/// Result from CheckCliAuthCommand
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CheckCliAuthResult {
    pub authenticated: bool,
    pub email: Option<String>,
    pub auth_method: Option<String>,
    /// Raw stdout from auth check command
    pub raw_output: String,
}

/// Input for RunCliLoginCommand — spawns the CLI login flow and extracts the OAuth URL
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandRunCliLoginData {
    pub cli_path: String,
    pub login_args: Vec<String>,
    #[serde(default)]
    pub auth_env: HashMap<String, String>,
}

/// Result from RunCliLoginCommand
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RunCliLoginResult {
    /// OAuth URL extracted from the CLI's output (open in browser)
    pub auth_url: Option<String>,
    pub raw_output: String,
}

// ---- App API Tier 1 — request/response types ----

/// Request for agent.open — find or create an agent pane for the given agent_id.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandAgentOpenData {
    pub agent_id: String,
    pub tab_id: Option<String>,
    pub split_direction: Option<String>,
    pub split_reference_block_id: Option<String>,
    pub focus: Option<bool>,
}

/// Request for agent.send — send a message to an agent pane.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandAgentSendData {
    pub block_id: String,
    pub message: String,
}

/// Request for agent.stop — stop a running agent subprocess.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandAgentStopApiData {
    pub block_id: String,
    pub signal: Option<String>,
}

/// Request for agent.status — query status of an agent pane.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandAgentStatusData {
    pub block_id: String,
}

/// Request for agent.output — read buffered output lines from an agent pane.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandAgentOutputData {
    pub block_id: String,
    pub after_line: Option<usize>,
    pub max_lines: Option<usize>,
}

/// Request for agent.stream — subscribe to live output from an agent pane.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandAgentStreamData {
    pub block_id: String,
}

/// Response from agent.open.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct AgentOpenResult {
    pub block_id: String,
    pub tab_id: String,
    pub agent_id: String,
    pub provider: String,
    pub controller_type: String,
    pub status: String,
    pub created: bool,
}

/// Request for pane.open — create a new pane showing the given view.
///
/// Supported views: `editor`, `term`, `browser`, `sysinfo`, `help`.
/// `file` is required for `editor`; `url` is required for `browser`.
/// Placement: if `split_direction` ("right" / "left" / "down" / "up")
/// and `split_reference_block_id` are provided, the new pane splits
/// relative to that block. Otherwise it is inserted at the tab root.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandPaneOpenData {
    pub view: String,
    pub file: Option<String>,
    pub url: Option<String>,
    pub cwd: Option<String>,
    pub title: Option<String>,
    pub tab_id: Option<String>,
    pub split_direction: Option<String>,
    pub split_reference_block_id: Option<String>,
    pub focus: Option<bool>,
}

/// Response from pane.open.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct PaneOpenResult {
    pub block_id: String,
    pub tab_id: String,
    pub view: String,
    pub created: bool,
}

/// Response from agent.send.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct AgentSendResult {
    pub block_id: String,
    pub status: String,
    pub session_id: Option<String>,
}

/// Response from agent.stop.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct AgentStopResult {
    pub block_id: String,
    pub status: String,
    pub exit_code: Option<i32>,
}

/// Response from agent.status.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct AgentStatusResult {
    pub block_id: String,
    pub agent_id: String,
    pub provider: String,
    pub controller_type: String,
    pub status: String,
    pub session_id: Option<String>,
    pub pid: Option<u32>,
    pub exit_code: Option<i32>,
}

/// A single entry in the agent.list response.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct AgentListEntry {
    pub block_id: String,
    pub tab_id: String,
    pub agent_id: String,
    pub provider: String,
    pub status: String,
    pub session_id: Option<String>,
}

/// Response from agent.list.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct AgentListResult {
    pub agents: Vec<AgentListEntry>,
}

/// Response from agent.output.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct AgentOutputResult {
    pub block_id: String,
    pub lines: Vec<String>,
    pub total_lines: usize,
    pub has_more: bool,
}

/// Request for `agent.process-list` — processes tracked under a given block.
#[derive(Debug, Clone, Deserialize)]
pub struct AgentProcessListCommand {
    pub block_id: String,
}

/// One tracked process row. Mirrors `backend::process_tracker::TrackedProcess`
/// — defined here so the RPC layer can expose it without leaking the
/// internal module shape.
#[derive(Debug, Clone, Serialize)]
pub struct AgentProcessInfo {
    pub pid: u32,
    pub command: String,
    pub rss_bytes: u64,
    pub started_at_ms: u64,
}

/// Response from `agent.process-list`.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct AgentProcessListResult {
    pub block_id: String,
    /// Platform confidence level — `"high"`, `"best_effort"`, `"none"`.
    /// Frontend shows a badge when anything less than `high`.
    pub confidence: String,
    pub processes: Vec<AgentProcessInfo>,
}

/// Response from `agent.tracked-blocks` — the list of block IDs for
/// which a tracker exists. Swarm pane uses this to render per-agent
/// groups.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct AgentTrackedBlocksResult {
    pub block_ids: Vec<String>,
}

/// Request for `agent.kill-process` — terminate a single PID if it's
/// in a given block's tracker tree.
#[derive(Debug, Clone, Deserialize)]
pub struct AgentKillProcessCommand {
    pub block_id: String,
    pub pid: u32,
}

/// Request for `agent.kill-tree` — nuke every process tracked under a
/// given block.
#[derive(Debug, Clone, Deserialize)]
pub struct AgentKillTreeCommand {
    pub block_id: String,
}

/// Response from `agent.kill-process` / `agent.kill-tree`.
/// `ok: true` means the kill was dispatched; it does NOT guarantee
/// the OS has fully torn down every descendant by the time the RPC
/// returns. The swarm activity panel's next refresh will reflect
/// actual state.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct AgentKillResult {
    pub ok: bool,
}

/// Request for blockfile:line_count — count total lines in a blockfile.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandBlockfileLineCountData {
    pub block_id: String,
    pub filename: String,
}

/// Response from blockfile:line_count.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct BlockfileLineCountResult {
    pub count: u64,
}

/// Request for blockfile:read_range — read a range of lines from a blockfile.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandBlockfileReadRangeData {
    pub block_id: String,
    pub filename: String,
    pub offset: u64,
    pub limit: u64,
}

/// Response from blockfile:read_range.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct BlockfileReadRangeResult {
    pub lines: Vec<String>,
    pub total: u64,
}

/// Request for blockfile:read_state — read a sidecar JSON file
/// (e.g. `output.state.json`) associated with a block.
/// Spec: docs/specs/SPEC_AGENT_PANE_STATE_PERSISTENCE_2026_05_15.md.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandBlockfileReadStateData {
    pub block_id: String,
    /// Sidecar filename — e.g. "output.state.json". Resolved within the
    /// block's filestore directory; must not contain path separators.
    pub filename: String,
}

/// Response from blockfile:read_state. `content` is the raw file bytes
/// as a UTF-8 string, or null if the sidecar does not exist.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct BlockfileReadStateResult {
    pub content: Option<String>,
}

/// Request for blockfile:write_state — atomically write a sidecar JSON
/// file for a block. Uses tmp + fsync + rename to guarantee partial
/// writes never surface to readers.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandBlockfileWriteStateData {
    pub block_id: String,
    pub filename: String,
    pub content: String,
}

/// Response from blockfile:write_state.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct BlockfileWriteStateResult {
    pub bytes_written: u64,
}

// ---- Session digest types ----

/// Request for session:digest — generate or return a cached AI summary of the session.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandSessionDigestData {
    pub block_id: String,
    /// If true, regenerate even if a cached digest exists.
    pub force: Option<bool>,
}

/// Response from session:digest.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct SessionDigestResult {
    /// AI-generated summary text (Markdown).
    pub summary: String,
    /// Unix milliseconds when this digest was generated.
    pub generated_at: i64,
    /// true if we returned a previously-cached result (no new activity since last run).
    pub cached: bool,
}

// ---- Session archival types ----

/// Request for session:archive — compress and archive a session's FileStore output.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandSessionArchiveData {
    pub block_id: String,
}

/// Response from session:archive.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct SessionArchiveResult {
    pub block_id: String,
    pub archived_bytes: u64,
    pub archived_at: i64,
}

/// Request for session:restore — decompress archive back into FileStore.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandSessionRestoreData {
    pub block_id: String,
}

/// Response from session:restore.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct SessionRestoreResult {
    pub block_id: String,
    pub restored_bytes: u64,
}

/// Request for session:export — read session output and return as base64 JSONL.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandSessionExportData {
    pub block_id: String,
}

/// Response from session:export.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct SessionExportResult {
    /// base64-encoded JSONL content (the raw output file bytes).
    pub content: String,
    pub line_count: u64,
    pub byte_count: u64,
}

/// Matches Go's `FileDataAt`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FileDataAt {
    pub offset: i64,
    #[serde(default, skip_serializing_if = "is_zero_usize")]
    pub size: usize,
}

/// Matches Go's `FileData`
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct FileData {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub info: Option<FileInfo>,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub data64: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub entries: Option<Vec<FileInfo>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub at: Option<FileDataAt>,
}

/// Matches Go's `FileInfo`
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct FileInfo {
    pub path: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub dir: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub name: String,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub notfound: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub opts: Option<FileOpts>,
    #[serde(default, skip_serializing_if = "is_zero_i64")]
    pub size: i64,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub meta: Option<HashMap<String, serde_json::Value>>,
    #[serde(default, skip_serializing_if = "is_zero_i64")]
    pub modtime: i64,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub isdir: bool,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub mimetype: String,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub readonly: bool,
}

/// Matches Go's `FileOpts`
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct FileOpts {
    #[serde(default, skip_serializing_if = "is_zero_i64")]
    pub maxsize: i64,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub circular: bool,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub ijson: bool,
    #[serde(default, skip_serializing_if = "is_zero_usize")]
    pub ijsonbudget: usize,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub truncate: bool,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub append: bool,
}

/// Matches Go's `CommandEventReadHistoryData`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandEventReadHistoryData {
    pub event: String,
    pub scope: String,
    #[serde(default)]
    pub maxitems: usize,
}

/// Matches Go's `CommandWaitForRouteData`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandWaitForRouteData {
    pub routeid: String,
    #[serde(default)]
    pub waitms: i64,
}

/// Matches Go's `BlockInfoData`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BlockInfoData {
    pub blockid: String,
    pub tabid: String,
    pub workspaceid: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub block: Option<Block>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub files: Option<Vec<FileInfo>>,
}

/// Matches Go's `WaveInfoData`
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct WaveInfoData {
    #[serde(default)]
    pub version: String,
    #[serde(default)]
    pub clientid: String,
    #[serde(default)]
    pub buildtime: String,
    #[serde(default)]
    pub configdir: String,
    #[serde(default)]
    pub datadir: String,
}

/// Matches Go's `WorkspaceInfoData`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WorkspaceInfoData {
    pub windowid: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workspacedata: Option<Workspace>,
}

/// Matches Go's `ConnStatus`
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct ConnStatus {
    pub status: String,
    #[serde(default)]
    pub connection: String,
    #[serde(default)]
    pub connected: bool,
    #[serde(default)]
    pub hasconnected: bool,
    #[serde(default)]
    pub activeconnnum: i32,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub error: String,
}

/// Matches Go's `WaveNotificationOptions`
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct WaveNotificationOptions {
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub title: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub body: String,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub silent: bool,
}

/// Matches Go's `RpcOpts`
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct RpcOpts {
    #[serde(default, skip_serializing_if = "is_zero_i64")]
    pub timeout: i64,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub noresponse: bool,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub route: String,
}

/// Matches Go's `RpcContext`
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct RpcContext {
    #[serde(default, skip_serializing_if = "String::is_empty", rename = "ctype")]
    pub client_type: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub blockid: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub tabid: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub conn: String,
}

/// Matches Go's `CommandVarData`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandVarData {
    pub key: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub val: String,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub remove: bool,
    #[serde(default)]
    pub zoneid: String,
    #[serde(default)]
    pub filename: String,
}

/// Matches Go's `CommandVarResponseData`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandVarResponseData {
    pub key: String,
    #[serde(default)]
    pub val: String,
    #[serde(default)]
    pub exists: bool,
}

/// Matches Go's `TimeSeriesData`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TimeSeriesData {
    pub ts: i64,
    pub values: HashMap<String, f64>,
}

/// Matches Go's `RemoteInfo`
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct RemoteInfo {
    #[serde(default)]
    pub clientarch: String,
    #[serde(default)]
    pub clientos: String,
    #[serde(default)]
    pub clientversion: String,
    #[serde(default)]
    pub shell: String,
}

// ---- Helper functions ----

fn is_zero_i64(v: &i64) -> bool {
    *v == 0
}

fn is_zero_usize(v: &usize) -> bool {
    *v == 0
}

// ---- Agent command data types ----

/// Optional filter input for `listagents`. When `is_seeded` is set,
/// only definitions whose `is_seeded` column matches are returned
/// (`Some(1)` → templates only; `Some(0)` → user-owned agents only).
/// Absent / `None` = no filter — backward-compatible with callers
/// that pass `{}` or `null`. Phase 1 of the two-tier picker
/// (SPEC_AGENT_PICKER_TWO_TIER_2026_05_24.md).
///
/// `include_hidden` (Phase 2 — Q2 Decision Y): when `false` (default),
/// templates with `user_hidden = 1` are filtered out. The settings
/// "Hidden templates" surface passes `true` so it can render rows for
/// unhiding; the picker proper omits the flag and gets the filtered
/// default. `include_hidden` only affects templates — user-owned rows
/// never set `user_hidden`, so the flag is a no-op for them.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct CommandListAgentDefinitionsData {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub is_seeded: Option<i64>,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub include_hidden: bool,
}

/// Request for `agentdefcreatefromtemplate`. Clones a seeded template
/// into a new user-owned definition. Phase 1 of the two-tier picker.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandAgentDefCreateFromTemplateData {
    /// id of a seeded definition (must have `is_seeded = 1`).
    pub template_id: String,
    /// User-chosen display name for the new agent. Non-empty, ≤200
    /// chars, must not collide with another user-owned agent's name.
    pub name: String,
    /// Identity bundle id to bind (empty string = ambient creds).
    /// Stored on the launch-time `db_agent_instances` row by the
    /// launch flow; the definition itself doesn't hold bindings
    /// pre-Phase 3, so this is reserved for the frontend to thread
    /// through to its subsequent `launchAgentDefinition` call. The
    /// server returns it back in the response for symmetry +
    /// future-proofing.
    #[serde(default)]
    pub identity_id: String,
    /// Memory bundle id to bind (empty string = vanilla CLI).
    /// Same semantics as `identity_id` above.
    #[serde(default)]
    pub memory_id: String,
}

/// Response for `agentdefcreatefromtemplate`. The frontend uses
/// `definition_id` to launch the freshly-created agent.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentDefCreateFromTemplateResult {
    pub definition_id: String,
    /// Echoed back so the caller's launch step doesn't need to
    /// re-thread these — they flow through to the launch overrides.
    pub identity_id: String,
    pub memory_id: String,
}

/// Request for `agentdefhide` / `agentdefunhide`. Phase 2 of the
/// two-tier picker (Q2 Decision Y). The two RPCs share the same shape
/// — the action is encoded in the command name, not the payload.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandAgentDefHideData {
    /// id of a seeded definition (must have `is_seeded = 1`).
    pub definition_id: String,
}

/// Response for `agentdefhide` / `agentdefunhide`. `ok = true` when a
/// row was updated; `false` when the id didn't match any row. (A row
/// that exists but isn't a template returns an RPC-level error, not
/// `ok: false` — the caller should never have been able to send that
/// id from the picker UI.)
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentDefHideResult {
    pub ok: bool,
}

/// Input for createagent
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandCreateAgentDefinitionData {
    pub name: String,
    #[serde(default = "default_agent_icon")]
    pub icon: String,
    pub provider: String,
    #[serde(default)]
    pub description: String,
    #[serde(default)]
    pub working_directory: String,
    #[serde(default)]
    pub shell: String,
    #[serde(default)]
    pub provider_flags: String,
    #[serde(default)]
    pub auto_start: i64,
    #[serde(default)]
    pub restart_on_crash: i64,
    #[serde(default)]
    pub idle_timeout_minutes: i64,
    #[serde(default = "default_agent_type")]
    pub agent_type: String,
    #[serde(default)]
    pub environment: String,
    #[serde(default)]
    pub agent_bus_id: String,
}

fn default_agent_type() -> String {
    "standalone".to_string()
}

fn default_agent_icon() -> String {
    "✦".to_string()
}

/// Input for updateagent
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandUpdateAgentDefinitionData {
    pub id: String,
    pub name: String,
    pub icon: String,
    pub provider: String,
    #[serde(default)]
    pub description: String,
    #[serde(default)]
    pub working_directory: String,
    #[serde(default)]
    pub shell: String,
    #[serde(default)]
    pub provider_flags: String,
    #[serde(default)]
    pub auto_start: i64,
    #[serde(default)]
    pub restart_on_crash: i64,
    #[serde(default)]
    pub idle_timeout_minutes: i64,
    #[serde(default = "default_agent_type")]
    pub agent_type: String,
    #[serde(default)]
    pub environment: String,
    #[serde(default)]
    pub agent_bus_id: String,
    /// JSON-encoded per-provider account assignments (see
    /// `AgentDefinition.accounts`). Written by the Agent pane's Identity tab.
    #[serde(default)]
    pub accounts: String,
}

/// Input for deleteagent
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandDeleteAgentDefinitionData {
    pub id: String,
}

/// Input for getagentcontent
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandGetAgentContentData {
    pub agent_id: String,
    pub content_type: String,
}

/// Input for setagentcontent
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandSetAgentContentData {
    pub agent_id: String,
    pub content_type: String,
    pub content: String,
}

/// Input for getallagentcontent
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandGetAllAgentContentData {
    pub agent_id: String,
}

// ---- Agent Skills command data types ----

/// Input for listagentskills
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandListAgentSkillsData {
    pub agent_id: String,
}

/// Input for createagentskill
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandCreateAgentSkillData {
    pub agent_id: String,
    pub name: String,
    #[serde(default)]
    pub trigger: String,
    #[serde(default = "default_skill_type")]
    pub skill_type: String,
    #[serde(default)]
    pub description: String,
    #[serde(default)]
    pub content: String,
}

fn default_skill_type() -> String {
    "prompt".to_string()
}

/// Input for updateagentskill
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandUpdateAgentSkillData {
    pub id: String,
    pub name: String,
    #[serde(default)]
    pub trigger: String,
    #[serde(default)]
    pub skill_type: String,
    #[serde(default)]
    pub description: String,
    #[serde(default)]
    pub content: String,
}

/// Input for deleteagentskill
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandDeleteAgentSkillData {
    pub id: String,
}

// ---- Agent History command data types ----

/// Input for appendagenthistory
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandAppendAgentHistoryData {
    pub agent_id: String,
    pub entry: String,
}

/// Input for listagenthistory
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandListAgentHistoryData {
    pub agent_id: String,
    #[serde(default)]
    pub session_date: Option<String>,
    #[serde(default = "default_history_limit")]
    pub limit: i64,
    #[serde(default)]
    pub offset: i64,
}

fn default_history_limit() -> i64 {
    50
}

/// Input for searchagenthistory
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandSearchAgentHistoryData {
    pub agent_id: String,
    pub query: String,
    #[serde(default = "default_history_limit")]
    pub limit: i64,
}

// ---- Agent Import command data types ----

/// Input for importagentfromclaw
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandImportAgentFromClawData {
    pub workspace_path: String,
    pub agent_name: String,
}

/// Input for importagents
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandImportAgentDefinitionsData {
    pub agents: Vec<AgentDefinitionImport>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentDefinitionImport {
    pub id: String,
    pub name: String,
    pub icon: String,
    pub description: String,
    pub provider: String,
    pub shell: String,
    pub working_directory: String,
    pub agent_bus_id: String,
    pub agent_type: String,
    pub environment: String,
    pub restart_on_crash: bool,
    pub content: std::collections::HashMap<String, String>,
    pub skills: Vec<AgentSkillImport>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentSkillImport {
    pub name: String,
    pub trigger: String,
    pub skill_type: String,
    pub description: String,
    pub content: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ImportAgentDefinitionsResult {
    pub imported: Vec<String>,
    pub skipped: Vec<String>,
    pub failed: Vec<String>,
}

/// Response for exportagents
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ExportAgentDefinitionsResult {
    pub version: u32,
    pub exported_at: String,
    pub source: String,
    pub agents: Vec<AgentDefinitionExport>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentDefinitionExport {
    pub id: String,
    pub name: String,
    pub icon: String,
    pub description: String,
    pub provider: String,
    pub shell: String,
    pub working_directory: String,
    pub agent_bus_id: String,
    pub agent_type: String,
    pub environment: String,
    pub restart_on_crash: bool,
    pub content: std::collections::HashMap<String, String>,
    pub skills: Vec<AgentSkillExport>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentSkillExport {
    pub name: String,
    pub trigger: String,
    pub skill_type: String,
    pub description: String,
    pub content: String,
}

// ====================================================================
// Tool store commands
// ====================================================================

pub const COMMAND_GET_TOOL_STATUS: &str = "gettoolstatus";
pub const COMMAND_INSTALL_TOOL: &str = "installtool";

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct CommandInstallToolData {
    pub tool_ids: Vec<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GetToolStatusResult {
    pub tools: Vec<crate::backend::tool_store::ToolStatusEntry>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct InstallToolResult {
    pub installed: Vec<String>,
    pub failed: Vec<InstallFailure>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct InstallFailure {
    pub id: String,
    pub error: String,
}

// ====================================================================
// Identity / Instance / Fork payloads (v6)
// See specs/SPEC_FORGE_IDENTITY_AGENT_INSTANCES_IMPL_2026_04_20.md.
// Strings use snake_case for cross-language parity with wstore.
// ====================================================================

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct CommandListIdentityAccountsData {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub provider: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandGetIdentityAccountData {
    pub id: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandDeleteIdentityAccountData {
    pub id: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandLinkAgentIdentityData {
    pub agent_id: String,
    pub account_id: String,
    pub provider: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandUnlinkAgentIdentityData {
    pub agent_id: String,
    pub provider: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandListAgentIdentitiesData {
    pub agent_id: String,
}

// ---- v7 Identity bundle command shapes ----

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandGetIdentityBundleData {
    pub id: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandDeleteIdentityBundleData {
    pub id: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandBindIdentityAccountData {
    pub identity_id: String,
    pub provider: String,
    pub account_id: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandUnbindIdentityAccountData {
    pub identity_id: String,
    pub provider: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandListIdentityBindingsData {
    pub identity_id: String,
}

// ---- v7 Memory bundle command shapes ----

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandGetMemoryData {
    pub id: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandDeleteMemoryData {
    pub id: String,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct CommandListAgentInstancesData {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub definition_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub status: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandGetAgentInstanceData {
    pub id: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandCreateAgentInstanceData {
    pub definition_id: String,
    #[serde(default)]
    pub block_id: String,
    #[serde(default)]
    pub parent_instance_id: String,
    /// FK to db_identity_bundles. Empty = blank singleton (no env-var
    /// injection; agent inherits ambient creds). Set by the launch
    /// modal's Identity dropdown.
    #[serde(default)]
    pub identity_id: String,
    /// FK to db_memory_bundles. Empty = blank singleton. Set by the launch
    /// modal's Memory dropdown.
    #[serde(default)]
    pub memory_id: String,
    /// User-chosen instance name (becomes `AGENTMUX_AGENT_ID` in the
    /// spawn env). Powers the launch modal's "Continue agent"
    /// dropdown. Empty = un-named, won't appear in the dropdown.
    #[serde(default)]
    pub instance_name: String,
    /// Absolute working directory path resolved by
    /// `allocate_agent_workdir` at spawn time. Stored on the instance
    /// row so the continue flow can reuse it without re-deriving the
    /// slug.
    #[serde(default)]
    pub working_directory: String,
}

/// Request for `listnamedagents`. The launch modal's "Continue
/// agent" dropdown calls this; an absent / zero `limit` defaults to
/// 200 (capped at 1000 to keep the wire payload bounded).
///
/// `definition_id` is server-side filtering: when provided, only
/// instances of that definition are returned. Required for the
/// dropdown to behave correctly when a user has 200+ named agents
/// across many definitions — without server filtering, the current
/// definition's older instances could fall off the global cap.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct CommandListNamedAgentsData {
    #[serde(default)]
    pub limit: usize,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub definition_id: Option<String>,
}

/// One row of the launch modal's "Continue agent" dropdown. Joins
/// `db_agent_instances` with `db_agent_definitions` (for the definition's
/// display name + provider) and `db_identity_bundles` / `db_memory_bundles`
/// (for bundle names) so the frontend renders without further lookups.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NamedAgentRow {
    pub instance_id: String,
    pub instance_name: String,
    pub definition_id: String,
    pub definition_name: String,
    pub provider: String,
    pub working_directory: String,
    pub identity_id: String,
    pub identity_name: String,
    pub memory_id: String,
    pub memory_name: String,
    pub started_at: i64,
    pub ended_at: i64,
    pub status: String,
    pub block_id_hint: String,
}

/// Request for `hidenamedagent`. Sets `display_hidden = 1` on the
/// row. Row + working directory remain on disk for audit + recovery
/// (destructive deletion is a separate, confirm-gated flow).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandHideNamedAgentData {
    pub id: String,
}

/// Request for `listrecentsessions` — powers the AgentPicker's "Recent
/// sessions" surface (cascade follow-up, 2026-05-23). Optional
/// `identity_id` filter narrows the results to sessions that used the
/// given identity bundle (matches `db_agent_instances.identity_id`).
/// `limit` defaults to 20 (capped at 100); rows are sorted by the
/// most-recent activity timestamp (filestore `output.state.json` modts
/// when available, otherwise instance `started_at`).
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct CommandListRecentSessionsData {
    #[serde(default)]
    pub limit: usize,
    /// When set + non-empty, filter to sessions whose `identity_id`
    /// matches. `Some("")` is treated the same as `None` (no filter)
    /// to make the frontend wiring straightforward.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub identity_id: Option<String>,
}

/// One row of the AgentPicker's "Recent sessions" list. Mirrors
/// `NamedAgentRow` but adds preview fields read from the per-block
/// `output.state.json` snapshot in filestore. `node_count == 0` and an
/// empty `preview` mean the snapshot wasn't readable (the block may
/// pre-date the persistence flow or have crashed before its first
/// 30s snapshot) — the row still surfaces so the user can reattach.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RecentSessionRow {
    pub instance_id: String,
    pub instance_name: String,
    pub definition_id: String,
    pub definition_name: String,
    pub provider: String,
    pub working_directory: String,
    pub identity_id: String,
    pub identity_name: String,
    pub memory_id: String,
    pub memory_name: String,
    /// The pane / block whose filestore zone holds the conversation.
    /// Empty when the instance row exists but no SQLite row resolved
    /// the block_id (cross-version registry rows). Reattach falls
    /// back to the working-directory continuation path in that case.
    pub block_id_hint: String,
    /// The CLI-emitted session id (`session_id` for Claude/Gemini,
    /// `thread_id` for Codex) captured during the prior run. Empty
    /// when the row predates the capture, the CLI didn't emit a
    /// session id, or the instance was created via a path that
    /// doesn't go through the spawn that captures it. Used by the
    /// picker reattach flow to populate `agent:sessionid` on the new
    /// block's meta so the spawned subprocess gets a real
    /// `--resume <sid>` on the FIRST turn instead of starting a
    /// fresh conversation that re-injects the startup context.
    #[serde(default)]
    pub session_id: String,
    /// Snapshot of the first user message in the conversation (up to
    /// 240 chars, newlines collapsed). Empty when the snapshot doesn't
    /// exist or doesn't contain a user_message node yet.
    pub preview: String,
    /// Total `nodes.length` from the snapshot. 0 when unavailable.
    pub node_count: usize,
    /// Last activity timestamp (filestore modts when the snapshot
    /// exists, otherwise `started_at`). Drives the sort order.
    pub last_active_at: i64,
    /// Whether `output.state.json` was found in filestore for this
    /// block. False when the snapshot doesn't exist yet (no preview)
    /// or the block_id_hint was empty.
    pub has_snapshot: bool,
}

/// Mutable subset of AgentInstance for PATCH-style updates. Every field is
/// optional — absent fields preserve their current value.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandUpdateAgentInstanceData {
    pub id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub block_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub session_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub status: Option<String>,
    /// JSON-encoded `GitHubContext` or empty string. `None` = leave as-is;
    /// `Some("")` = explicitly clear.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub github_context: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ended_at: Option<i64>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandDeleteAgentInstanceData {
    pub id: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandForkAgentDefinitionData {
    pub source_id: String,
    #[serde(default)]
    pub branch_label: String,
}

// ====================================================================
// Option E — agent-anchored session zones (PR 1 of 2)
// See docs/specs/SPEC_CONTINUATION_SESSION_PERSISTENCE_2026_05_23.md.
// ====================================================================

/// Request for `agent:session:read`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandAgentSessionReadData {
    pub definition_id: String,
}

/// Response for `agent:session:read`. `content == None` means no zone /
/// snapshot exists for this definition (NOT an error — fresh agent).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentSessionReadResult {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub content: Option<String>,
    /// `modts` of the `output.state.json` file in the agent's
    /// `:current` zone, if it exists.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub modts: Option<i64>,
}

/// Request for `agent:session:write_state`. Writes `output.state.json`
/// into `agent:<definition_id>:current` (creates the zone if missing).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandAgentSessionWriteStateData {
    pub definition_id: String,
    pub content: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentSessionWriteStateResult {
    pub bytes_written: u64,
}

/// Request for `agent:session:append_output`. Appends a single
/// NDJSON line to `output` in `agent:<definition_id>:current`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandAgentSessionAppendOutputData {
    pub definition_id: String,
    pub line: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentSessionAppendOutputResult {
    pub bytes_written: u64,
}

/// Request for `agent:session:archive`. Snapshots `agent:<defId>:current`
/// into `agent:<defId>:archive:<now_ms>` then clears the current zone.
/// Returns the archive zoneid (empty if no-op).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandAgentSessionArchiveData {
    pub definition_id: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentSessionArchiveResult {
    /// Empty string when nothing was archived (current zone was empty).
    pub archive_zoneid: String,
    pub archived_at_ms: i64,
}

/// Request for `agent:session:list_archives`.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct CommandAgentSessionListArchivesData {
    pub definition_id: String,
    #[serde(default)]
    pub limit: usize,
}

/// One row of the agent's archive list. Mirrors `RecentSessionRow`
/// preview shape so the frontend can reuse the same row component.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentArchiveRow {
    pub archive_zoneid: String,
    pub archived_at_ms: i64,
    /// First user_message in the archived `output.state.json` (up to
    /// 240 chars, newlines collapsed). Empty when unreadable.
    pub preview: String,
    /// Total `nodes.length` from the archived snapshot. 0 when
    /// unreadable / missing.
    pub node_count: usize,
}

// ====================================================================
// Tests
// ====================================================================

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_rpc_message_command_roundtrip() {
        let msg = RpcMessage {
            command: "getmeta".to_string(),
            reqid: "req-123".to_string(),
            timeout: 5000,
            data: Some(serde_json::json!({"oref": "block:abc-123"})),
            ..Default::default()
        };
        let json = serde_json::to_string(&msg).unwrap();
        let parsed: RpcMessage = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.command, "getmeta");
        assert_eq!(parsed.reqid, "req-123");
        assert_eq!(parsed.timeout, 5000);
        assert!(parsed.data.is_some());
    }

    #[test]
    fn test_rpc_message_response_roundtrip() {
        let msg = RpcMessage {
            reqid: "req-123".to_string(),
            resid: "res-456".to_string(),
            data: Some(serde_json::json!({"view": "term"})),
            ..Default::default()
        };
        let json = serde_json::to_string(&msg).unwrap();
        let parsed: RpcMessage = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.reqid, "req-123");
        assert_eq!(parsed.resid, "res-456");
    }

    #[test]
    fn test_rpc_message_empty_fields_omitted() {
        let msg = RpcMessage {
            command: "test".to_string(),
            ..Default::default()
        };
        let json = serde_json::to_string(&msg).unwrap();
        assert!(!json.contains("reqid"));
        assert!(!json.contains("resid"));
        assert!(!json.contains("timeout"));
        assert!(!json.contains("cont"));
        assert!(!json.contains("cancel"));
    }

    #[test]
    fn test_rpc_message_validate_command() {
        let msg = RpcMessage {
            command: "getmeta".to_string(),
            ..Default::default()
        };
        assert!(msg.validate().is_ok());
    }

    #[test]
    fn test_rpc_message_validate_cancel() {
        let msg = RpcMessage {
            cancel: true,
            reqid: "req-1".to_string(),
            ..Default::default()
        };
        assert!(msg.validate().is_ok());

        // cancel without reqid or resid
        let bad = RpcMessage {
            cancel: true,
            ..Default::default()
        };
        assert!(bad.validate().is_err());
    }

    #[test]
    fn test_rpc_message_validate_empty() {
        let msg = RpcMessage::default();
        assert!(msg.validate().is_err());
    }

    #[test]
    fn test_rpc_message_validate_both_ids() {
        let msg = RpcMessage {
            reqid: "a".to_string(),
            resid: "b".to_string(),
            ..Default::default()
        };
        assert!(msg.validate().is_err());
    }

    #[test]
    fn test_command_get_meta_data() {
        let data = CommandGetMetaData {
            oref: ORef::new("block", "550e8400-e29b-41d4-a716-446655440000"),
        };
        let json = serde_json::to_string(&data).unwrap();
        let parsed: CommandGetMetaData = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.oref.otype, "block");
    }

    #[test]
    fn test_command_set_meta_data() {
        let mut meta = MetaMapType::new();
        meta.insert("view".into(), serde_json::json!("term"));

        let data = CommandSetMetaData {
            oref: ORef::new("block", "550e8400-e29b-41d4-a716-446655440000"),
            meta,
        };
        let json = serde_json::to_string(&data).unwrap();
        let parsed: CommandSetMetaData = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.meta["view"], "term");
    }

    #[test]
    fn test_wire_compat_go_rpc_message() {
        // Simulated Go-produced JSON
        let go_json = r#"{"command":"getmeta","reqid":"abc","timeout":5000,"data":{"oref":"block:123"}}"#;
        let msg: RpcMessage = serde_json::from_str(go_json).unwrap();
        assert_eq!(msg.command, "getmeta");
        assert_eq!(msg.reqid, "abc");
        assert_eq!(msg.timeout, 5000);
    }

    #[test]
    fn test_rpc_context_roundtrip() {
        let ctx = RpcContext {
            client_type: "connserver".to_string(),
            blockid: "blk-1".to_string(),
            tabid: "tab-1".to_string(),
            conn: "local".to_string(),
        };
        let json = serde_json::to_string(&ctx).unwrap();
        assert!(json.contains(r#""ctype":"connserver""#));
        let parsed: RpcContext = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.client_type, "connserver");
    }

    #[test]
    fn test_all_command_constants_non_empty() {
        // Verify all command constants are non-empty strings
        let commands = [
            COMMAND_AUTHENTICATE,
            COMMAND_AUTHENTICATE_TOKEN,
            COMMAND_DISPOSE,
            COMMAND_ROUTE_ANNOUNCE,
            COMMAND_ROUTE_UNANNOUNCE,
            COMMAND_MESSAGE,
            COMMAND_GET_META,
            COMMAND_SET_META,
            COMMAND_SET_VIEW,
            COMMAND_CONTROLLER_INPUT,
            COMMAND_CONTROLLER_STOP,
            COMMAND_CONTROLLER_RESYNC,
            COMMAND_CREATE_BLOCK,
            COMMAND_DELETE_BLOCK,
            COMMAND_FILE_READ,
            COMMAND_FILE_WRITE,
            COMMAND_FILE_APPEND,
            COMMAND_EVENT_PUBLISH,
            COMMAND_EVENT_SUB,
            COMMAND_EVENT_UNSUB,
            COMMAND_CONN_CONNECT,
            COMMAND_CONN_DISCONNECT,
            COMMAND_WORKSPACE_LIST,
            COMMAND_FOCUS_WINDOW,
            COMMAND_AI_SEND_MESSAGE,
        ];
        for cmd in &commands {
            assert!(!cmd.is_empty(), "command constant should not be empty");
        }
    }

    #[test]
    fn test_file_info_roundtrip() {
        let info = FileInfo {
            path: "/home/user/test.txt".to_string(),
            name: "test.txt".to_string(),
            size: 1024,
            isdir: false,
            mimetype: "text/plain".to_string(),
            ..Default::default()
        };
        let json = serde_json::to_string(&info).unwrap();
        let parsed: FileInfo = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.path, "/home/user/test.txt");
        assert_eq!(parsed.size, 1024);
    }

    #[test]
    fn test_conn_status_roundtrip() {
        let status = ConnStatus {
            status: "connected".to_string(),
            connection: "ssh:myhost".to_string(),
            connected: true,
            ..Default::default()
        };
        let json = serde_json::to_string(&status).unwrap();
        let parsed: ConnStatus = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.status, "connected");
        assert!(parsed.connected);
    }

    #[test]
    fn test_wave_info_data_roundtrip() {
        let info = WaveInfoData {
            version: "0.12.15".to_string(),
            clientid: "client-123".to_string(),
            ..Default::default()
        };
        let json = serde_json::to_string(&info).unwrap();
        let parsed: WaveInfoData = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.version, "0.12.15");
    }

    #[test]
    fn test_create_block_data_wire_compat() {
        let go_json = r#"{"tabid":"tab-1","blockdef":{"view":"term"},"magnified":true}"#;
        let parsed: CommandCreateBlockData = serde_json::from_str(go_json).unwrap();
        assert_eq!(parsed.tabid, "tab-1");
        assert!(parsed.magnified);
        assert!(parsed.blockdef.is_some());
    }
}