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_ROUTE_ANNOUNCE: &str = "routeannounce";
pub const COMMAND_ROUTE_UNANNOUNCE: &str = "routeunannounce";

// Core commands
pub const COMMAND_GET_META: &str = "getmeta";
pub const COMMAND_SET_META: &str = "setmeta";

// Controller commands
pub const COMMAND_CONTROLLER_INPUT: &str = "controllerinput";
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";
/// Deliver an AskUserQuestion answer to the running agent CLI as a tool_result.
/// Lowercase, no separators — matches the sibling command-name convention
/// (`agentinput`, `agentstop`, `tooldecision`).
/// Spec: docs/specs/SPEC_ASK_USER_QUESTION_2026_06_15.md.
pub const COMMAND_AGENT_ANSWER: &str = "agentanswer";
pub const COMMAND_AGENT_STOP: &str = "agentstop";
pub const COMMAND_SHELL_EXEC: &str = "shellexec";
/// Stop a running persistent shell node (Phase 3) — UI stop button.
pub const COMMAND_SHELL_STOP: &str = "shellstop";
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

// File commands

// Event commands
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

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

// Remote commands

// Info/activity commands
pub const COMMAND_APP_INFO: &str = "waveinfo";

// Connection commands
// 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

// UI commands

// VDom commands

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

// Screenshot

// RT info

// Terminal

// 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";
/// Trust Center: validate (optional, user-initiated) + securely store an API
/// key. The plaintext goes to the OS keychain; the DB keeps only a
/// `SecretRef::Keychain` pointer + masked tail + metadata. Used for both new
/// accounts and replacing a key on an existing one (via `accountId`).
/// See specs/SPEC_TRUST_CENTER_2026_06_15.md §5/§6.
pub const COMMAND_ACCOUNT_KEY_VERIFY: &str = "account.key.verify";
/// Trust Center service OAuth (scaffold — activates once client ids are
/// provisioned or supplied as BYO). See SPEC_TRUST_CENTER_2026_06_15.md §4.2.
pub const COMMAND_ACCOUNT_OAUTH_START: &str = "account.oauth.start";
pub const COMMAND_ACCOUNT_OAUTH_POLL: &str = "account.oauth.poll";
pub const COMMAND_ACCOUNT_OAUTH_CANCEL: &str = "account.oauth.cancel";

// 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";
/// v9 — set the global-brain section order. `ids` is the full ordered list
/// of global bundle ids; each row's `sort_order` becomes its index.
pub const COMMAND_REORDER_GLOBAL_BRAIN: &str = "reorderglobalbrain";

// 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";
/// Returns the suggested branch label for a fork without mutating anything.
/// Called when the user clicks "Open new session" to pre-fill the name input.
pub const COMMAND_FORK_AGENT_DEFINITION_SUGGEST: &str = "forkagentdefinitionsuggest";

/// 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";

/// Returns whether a usable container runtime is reachable RIGHT NOW —
/// i.e. the Docker daemon answers a `ping`, not merely that the `docker`
/// CLI is on PATH. Used by the create-from-template modal to decide
/// whether to offer/default the container runtime; a binary-only check
/// would false-positive when Docker is installed but the daemon is
/// stopped, steering the user into a container agent that can't start.
/// Response: `{ "available": bool }`.
pub const COMMAND_CONTAINER_RUNTIME_AVAILABLE: &str = "containerruntimeavailable";

/// 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";
/// 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";
/// Create or upsert an agent definition. Broadcasts `agents:changed` on
/// success so all open frontends refresh My Agents without a restart.
pub const COMMAND_AGENT_DEFINE: &str = "agent.define";

// 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";

// Per-turn live activity summary (Haiku-powered, writes term:activity)
pub const COMMAND_SESSION_ACTIVITY_SUMMARY: &str = "session:activity_summary";

// 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";

// ---- Native memory RPCs (Phase 2 — agent:memory:list / read / write) ----
pub const COMMAND_NATIVE_MEMORY_LIST: &str = "agent:memory:list";
pub const COMMAND_NATIVE_MEMORY_READ_FILE: &str = "agent:memory:read_file";
pub const COMMAND_NATIVE_MEMORY_WRITE_FILE: &str = "agent:memory:write_file";

// ---- 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>,
}

/// Data for AgentAnswerCommand — an AskUserQuestion answer delivered back to
/// the running agent CLI via the Agent SDK control protocol (a `control_response`
/// carrying `updatedInput.answers`). Spec:
/// docs/specs/SPEC_AGENT_CONTROL_PROTOCOL_2026_06_15.md.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct CommandAgentAnswerData {
    pub blockid: String,
    /// The `AskUserQuestion` tool_use id the answer responds to (correlates with
    /// the parked `can_use_tool` control_request).
    pub tool_use_id: String,
    /// The user's selections as a JSON object mapping each question's text to the
    /// chosen option label (a `[labels]` array for multiSelect, or free-text for
    /// "Other"). Becomes `updatedInput.answers` in the control_response.
    #[serde(default)]
    pub answers: serde_json::Value,
}

// ---- 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,
}

/// Data for ShellExecCommand — run a shell command in the agent's working directory.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandShellExecData {
    pub blockid: String,
    pub command: String,
    #[serde(default)]
    pub working_dir: String,
}

/// Result of ShellExecCommand.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ShellExecResult {
    pub exit_code: i32,
    pub stdout: String,
    pub stderr: String,
}

/// Data for ShellStopCommand — stop a running persistent shell node by id.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommandShellStopData {
    pub shell_id: String,
}

/// 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 agent.define — create or upsert an agent definition.
/// `if_exists` controls behaviour when a slug-matching definition exists:
///   `"skip"` (default) — return existing id unchanged
///   `"update"` — overwrite all provided non-empty fields
///   `"error"` — fail with an error message
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandAgentDefineData {
    pub name: String,
    #[serde(default)]
    pub provider: String,
    /// Alternative to `provider` — inferred from model prefix.
    /// If both are set, `provider` wins.
    #[serde(default)]
    pub model: String,
    #[serde(default)]
    pub icon: String,
    #[serde(default)]
    pub description: String,
    #[serde(default)]
    pub working_directory: String,
    #[serde(default)]
    pub shell: String,
    #[serde(default)]
    pub environment: String,
    /// System/instruction text written to the agent's CLAUDE.md on spawn.
    pub system_prompt: Option<String>,
    /// Extra env vars injected at agent spawn, stored as KEY=VALUE lines.
    pub env: Option<std::collections::HashMap<String, String>>,
    pub if_exists: Option<String>,
    pub create_instance_stub: Option<bool>,
    /// "host" or "container". Defaults to "host" when absent — the safe
    /// default that works without Docker. Callers must explicitly pass
    /// "container" so a missing field never silently starts the wrong runtime.
    #[serde(default = "default_host_agent_type")]
    pub agent_type: String,
    /// Docker image for container-type agents. Empty string for host agents.
    #[serde(default)]
    pub container_image: String,
    /// JSON array of volume mount specs. Empty array (`"[]"`) for host agents.
    #[serde(default = "default_container_volumes")]
    pub container_volumes: String,
}

fn default_host_agent_type() -> String {
    "host".to_string()
}

/// Response from agent.define.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct AgentDefineResult {
    pub definition_id: String,
    pub slug: String,
    pub action: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub instance_stub_id: Option<String>,
}

/// 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>,
    /// `editor` only: initial file-tree sidebar state. `Some(false)` opens the
    /// editor with its tree collapsed (just the file, no explorer). Written to
    /// `block.meta["editor:tree_expanded"]`, which the frontend `EditorViewModel`
    /// restores on init. Absent / `Some(true)` → the frontend default (expanded).
    pub tree_expanded: Option<bool>,
    /// `Some(true)` opens the pane as a floating window instead of a docked
    /// split. The block is created then moved into a fresh floating workspace
    /// via the `tear_off_block` saga; the launcher broadcasts an
    /// `openfloatingpane` directive scoped to the source window, whose frontend
    /// calls the host `open_floating_pane_window` command to materialize the OS
    /// window. `split_direction` / `split_reference_block_id` are ignored when
    /// floating. See docs/specs/SPEC_OPENEDITOR_FLOATING_AND_COLLAPSED_TREE_2026_06_16.md.
    pub floating: 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 activity summary types ----

/// Request for session:activity_summary — generate a per-turn live summary via Haiku.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "snake_case")]
pub struct CommandActivitySummaryData {
    pub block_id: String,
    /// Target word count, derived from pane width. Defaults to 7.
    pub word_target: Option<u32>,
}

/// Response from session:activity_summary. The backend also writes `term:activity` to block meta.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "snake_case")]
pub struct ActivitySummaryResult {
    pub summary: String,
}

// ---- 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,
    /// Runtime to persist on the cloned definition: "host" or
    /// "container". Empty/absent → keep the template's `agent_type`.
    /// Runtime is chosen at instantiation time, not a property of the
    /// template, so the clone records the user's pick rather than
    /// inheriting the (now container-defaulted) template value.
    #[serde(default)]
    pub agent_type: 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_container_volumes() -> String {
    "[]".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,
    /// Docker image for container-type agents. Empty string for host agents.
    #[serde(default)]
    pub container_image: String,
    /// JSON array of volume mount specs. Empty array (`"[]"`) for host agents.
    #[serde(default = "default_container_volumes")]
    pub container_volumes: 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)]
pub struct CommandReorderGlobalBrainData {
    /// Full ordered list of global bundle ids. Each id's `sort_order`
    /// becomes its position in this list.
    pub ids: Vec<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,
    /// When the agent definition was first created (ms since epoch).
    /// Shown as "Created" in the My Agents card.
    pub agent_created_at: i64,
    /// When this instance was last launched (ms since epoch).
    /// Shown as "Last Launch" in the My Agents card.
    pub started_at: i64,
    /// "host" or "container" — drives the runtime badge in the My Agents list.
    #[serde(default)]
    pub agent_type: String,
}

/// 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,
    /// When non-empty this becomes the fork's display name directly.
    /// When empty, the handler auto-generates "Name #N".
    #[serde(default)]
    pub branch_label: String,
}

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

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ForkAgentDefinitionSuggestResult {
    pub suggested_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,
}

// ====================================================================
// Native memory RPCs — agent:memory:list / read / write
// ====================================================================

/// Metadata for one `*.md` file in the agent's native memory folder.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NativeMemoryFileMeta {
    pub filename: String,
    /// True only for `MEMORY.md` (the Claude Code index file).
    pub is_index: bool,
    /// Parsed from YAML frontmatter `type:` field. Null when absent.
    pub metadata_type: Option<String>,
    pub size_bytes: u64,
    /// Unix timestamp in milliseconds.
    pub modified_at: i64,
}

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

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NativeMemoryListResult {
    pub files: Vec<NativeMemoryFileMeta>,
}

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

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

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

// ====================================================================
// 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_ROUTE_ANNOUNCE,
            COMMAND_ROUTE_UNANNOUNCE,
            COMMAND_GET_META,
            COMMAND_SET_META,
            COMMAND_CONTROLLER_INPUT,
            COMMAND_CONTROLLER_RESYNC,
            COMMAND_EVENT_SUB,
            COMMAND_EVENT_UNSUB,
        ];
        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());
    }
}