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
  • Coverage
  • 52.03%
    64 out of 123 items documented0 out of 44 items with examples
  • Size
  • Source code size: 53.3 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 1.1 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 10s Average build duration of successful builds.
  • all releases: 10s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • any-victor

herdr-sdk

A small synchronous client for Herdr's socket API: typed requests, an event stream, and the slice of Herdr's schema that plugins actually touch.

[dependencies]
herdr-sdk = "0.0.1"

▲ A 0.0.x requirement is exact in Cargo: "0.0.1" resolves only to 0.0.1, never to 0.0.2. That is the correct reading of where this is — bump it deliberately.

use herdr_sdk::{Client, model::PaneList};

let mut client = Client::connect()?;                     // $HERDR_SOCKET_PATH
let panes: PaneList = client.call("pane.list", serde_json::json!({}))?;

for pane in panes.panes {
    if let Some(cwd) = pane.cwd_resolved() {
        println!("{} · {} ({})", pane.label(), cwd.path, cwd.source);
    }
}

Herdr's own answer to "what is the plugin API" is the entire CLI — a plugin is a manifest plus any argv command, and HERDR_BIN_PATH is the portable way in. This crate is for the other case: a Rust plugin that would rather speak the socket directly than shell out per call, and would rather not hand-roll the parts of it that are surprising.

What it gives you

Module What it is
Client One request, one response. Dials per call, because Herdr answers the first request on a connection and then hangs up.
notify Fire-and-forget for callers on a latency budget — an agent hook, where every millisecond blocks a turn. No reply is read, so errors are silent.
Events A held-open events.subscribe that yields frames until Herdr hangs up.
model Pane, Agent, AgentSession, PluginContext and the list wrappers, every nullable field optional and serde(default) throughout.
cwd Where an agent is actually working, and how sure you can be.
subagents The in-process subagents inside one agent, which pane.list structurally cannot see.

The parts that are surprising

Each of these was measured against a running Herdr, not read from a spec. They are the reason this crate exists rather than a serde_json::to_writer call at each site.

  • One request per connection. The server answers the first request on a stream and then sends FIN; a second request on the same socket is never answered. Client therefore holds a path, not a stream.
  • Subscribe with dots, receive underscores. You subscribe to pane.updated and the frames arrive as pane_updated. Subscribing with the received spelling looks accepted and silently yields nothing, so EventKind owns both spellings and no call site writes either by hand.
  • pane.agent_status_changed is pane-scoped. Subscribing without a pane_id is rejected outright.
  • foreground_cwd cannot track a coding agent. It is the OS working directory of the pane's foreground process, and the agents that matter change directory internally without ever calling chdir — omp's /move and Claude Code's /cd both do. It stays a source; it must not be the only one, and it must not outrank the agent's own report. cwd resolves that precedence in one place.
  • pane.report_metadata truncates every string to 80 characters and still answers ok. That is why subagents carries a roster as a path rather than a payload — a single subject line can exceed 80 characters on its own.

Related

herdr-plugin is an async, tokio-based application framework for Herdr plugins, with a dispatcher, typed per-domain clients and plugin state. If you want a framework to build inside, start there. This crate is the smaller, synchronous option: no runtime, no application shape, just the socket and the models — which is what a threaded TUI or a one-shot hook usually wants.

Source

Developed in a private monorepo alongside the plugins that use it, and published here as a crate. Every source file ships in the published package, so docs.rs and cargo vendor show the whole thing.

Status

0.0.1 — first published version, extracted from the plugins it was written for. The surface covers what they need and grows by use rather than by anticipation: a generated binding for all 89 socket methods would be mostly dead code that still has to compile. Expect it to move; additions welcome.

MIT.