herdr-sdk 0.0.1

A small synchronous client for Herdr's socket API: typed requests, an event stream, and the pane and agent models plugins actually touch.
Documentation
//! The slice of Herdr's schema plugins actually touch.
//!
//! Every field is optional that Herdr declares nullable, and `serde(default)`
//! is on the containers: the socket gains fields between releases and a plugin
//! that hard-fails on an unknown shape is a plugin that breaks on upgrade.

use std::collections::HashMap;

use serde::Deserialize;

use crate::cwd::{self, Cwd};

/// How Herdr identifies the conversation running in a pane.
///
/// `kind` is `"id"` for a native conversation id (Claude) or `"path"` for a
/// transcript file (pi, omp). Either way `value` is **stable across panes**,
/// which is what makes it the right key for anything a user expects to still be
/// there after a pane is closed and the session resumed.
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(default)]
pub struct AgentSession {
    pub agent: String,
    pub kind: String,
    /// Which integration reported it, e.g. `herdr:omp`.
    pub source: String,
    pub value: String,
}

#[derive(Debug, Clone, Default, Deserialize)]
#[serde(default)]
pub struct Pane {
    pub pane_id: String,
    pub tab_id: String,
    pub workspace_id: String,
    pub focused: bool,
    pub agent: Option<String>,
    pub agent_status: Option<String>,
    pub terminal_title_stripped: Option<String>,
    /// What Herdr displays for the pane. Plugin panes get the title from their
    /// manifest here; agent panes generally do not have one.
    pub label: Option<String>,
    /// Monotonic per pane. Cheap change detection when a full diff is too much.
    pub revision: u64,
    /// The conversation in this pane, when an integration has reported one.
    pub agent_session: Option<AgentSession>,
    /// Free-form metadata any plugin may write with `pane.report_metadata`.
    ///
    /// ▲ One flat map per pane, **not** namespaced by the reporting `source`:
    /// writers prefix their own keys by convention and the last writer wins. A
    /// read only ever yields strings; the option exists because `null` is the
    /// erase value on the request side, and accepting it costs nothing.
    pub tokens: HashMap<String, Option<String>>,
    /// Where the pane was started.
    pub cwd: Option<String>,
    /// The OS working directory of the pane's foreground process.
    ///
    /// ▲ Not where an agent is working. See [`crate::cwd`] — and use
    /// [`Pane::cwd_resolved`] rather than reading this field directly.
    pub foreground_cwd: Option<String>,
}

impl Pane {
    /// The directory this pane is working in, and where that answer came from.
    ///
    /// The one place any plugin should ask. See [`crate::cwd`] for the
    /// precedence and why a single call site matters.
    pub fn cwd_resolved(&self) -> Option<Cwd<'_>> {
        cwd::resolve(self)
    }

    /// The reported session's stable identity, when there is one.
    pub fn session_id(&self) -> Option<&str> {
        self.agent_session
            .as_ref()
            .map(|session| session.value.as_str())
            .filter(|value| !value.is_empty())
    }

    /// What to call this agent in a list.
    pub fn label(&self) -> String {
        match (&self.agent, &self.terminal_title_stripped) {
            (Some(agent), Some(title)) if !title.is_empty() => format!("{agent} · {title}"),
            (Some(agent), _) => agent.clone(),
            _ => self.pane_id.clone(),
        }
    }
}

#[derive(Debug, Clone, Default, Deserialize)]
#[serde(default)]
pub struct Agent {
    pub pane_id: String,
    pub workspace_id: String,
    pub agent: Option<String>,
    pub agent_status: Option<String>,
    pub focused: bool,
    pub cwd: Option<String>,
    pub foreground_cwd: Option<String>,
    pub terminal_title_stripped: Option<String>,
}

#[derive(Debug, Clone, Default, Deserialize)]
#[serde(default)]
pub struct PluginContext {
    pub workspace_id: Option<String>,
    pub workspace_label: Option<String>,
    pub workspace_cwd: Option<String>,
    pub focused_pane_id: Option<String>,
    pub focused_pane_cwd: Option<String>,
    pub focused_pane_agent: Option<String>,
    pub tab_id: Option<String>,
    pub selected_text: Option<String>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct AgentList {
    #[serde(default)]
    pub agents: Vec<Agent>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct PaneList {
    #[serde(default)]
    pub panes: Vec<Pane>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct PaneCurrent {
    pub pane: Option<Pane>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct PaneInfo {
    pub pane: Option<Pane>,
}