@stateforge-labs/herdr-sdk 0.0.0-stage → 0.3.0

package/schema/herdr-version.json

@@ -0,0 +1,5 @@
+{
+  "version": "0.9.5",
+  "protocol": 22,
+  "captured": "2026-11-02"
+}

package/skills/herdr-sdk/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: herdr-sdk
+description: Write TypeScript or JavaScript that talks to a running herdr server (spaces/workspaces, tabs, panes, coding agents) through the typed @stateforge-labs/herdr-sdk client over herdr's unix socket. Use when code imports @stateforge-labs/herdr-sdk, or the task is to list, watch, prompt, wait on or read herdr panes and agents from a script, plugin, daemon or test, or to fake herdr in tests, or to talk to herdr-core (hc) over its socket. Not for driving the herdr CLI by hand (hc skill) or the GUI window (herdr-app skill).
+---
+
+# @stateforge-labs/herdr-sdk
+
+Typed client for herdr's socket API. Zero runtime dependencies, Bun and Node 22.18+. Targets **@stateforge-labs/herdr-sdk 0.3.0 = herdr protocol 22 (herdr 0.9.5)**.
+
+## First: check the version
+
+Do not trust memory of this API. Before writing code:
+
+1. Read `node_modules/@stateforge-labs/herdr-sdk/package.json`: `version` and `herdr.protocol` must match the line above. If they differ, this skill may be stale; read the package's `docs/api/methods.md` and `docs/api/events.md` (generated from the schema, always current) before trusting any name here.
+2. After editing, run the type checker. Param and result types are generated, so a wrong field name fails at compile time.
+
+## Pick the entry point (least power that works)
+
+| Import | Function | Can do | Cannot |
+|---|---|---|---|
+| `@stateforge-labs/herdr-sdk/read-only` | `connectReadOnly()` | structure reads (`*.list`, `*.get`, `session.snapshot`), long-poll waits, `events.subscribe`, `watch` | terminal content (opt in with `{ content: true }`), any write, generic `call()` |
+| `@stateforge-labs/herdr-sdk/read-only` | `connectPrompt()` | structure reads + `agent.prompt` | everything else |
+| `@stateforge-labs/herdr-sdk` | `connect()` | reads, content, UI changes, input, hooks, long-poll, `hold()` | destructive, server control, spawn/execute |
+| `@stateforge-labs/herdr-sdk/admin` | `connectAdmin()` | all 102 methods | nothing |
+| `@stateforge-labs/herdr-sdk/effect` | `Herdr` service + Layers | same as above as Effect (needs peer `effect` 4.1.2) | |
+| `@stateforge-labs/herdr-sdk/test-kit` | `createFakeHerdr()` | in-process fake server for tests | production use |
+| `@stateforge-labs/herdr-sdk/schema` | method table, param shapes | tooling that reflects on the API | |
+| `@stateforge-labs/herdr-sdk/core` | `CoreLink`, `CoreEvents`, wire parsers, `hcCoreSocketPath()` | a client of the herdr-core (`hc`) socket: calls, the event feed with heartbeats, failures as `Unknown` values | the protocol-22 herdr socket |
+| `@stateforge-labs/herdr-sdk/core/test-kit` | `FakeHcCore`, `setupTest(t)`, `openWorld()` | a scripted fake herdr-core for tests | production use |
+
+Start with `connectReadOnly()`. Use `connectAdmin()` only for `*.close`, `server.*`, `agent.start`, `plugin.*`: say why in a comment.
+
+## Minimal use
+
+```ts run
+// fake: agent.list {"type":"agent_list","agents":[{"agent_status":"idle","focused":false,"pane_id":"p_1","revision":1,"tab_id":"t_1","terminal_id":"term_1","workspace_id":"w_1","name":"reviewer"}]}
+import { connect, HerdrError } from "@stateforge-labs/herdr-sdk"
+
+const herdr = await connect() // HERDR_SOCKET, else ~/.config/herdr/herdr.sock; pings; checks protocol 22
+try {
+  const { agents } = await herdr.agent.list({})
+  for (const agent of agents) console.log(agent.name, agent.agent_status)
+} catch (error) {
+  if (error instanceof HerdrError) console.error(error.code, error.message)
+  else throw error
+} finally {
+  herdr.close()
+}
+```
+
+Methods are nested by their dotted wire name: `herdr.pane.list({})`, `herdr.agent.view.set({...})`. Every method takes one params object (`{}` when empty).
+
+## Rules
+
+- **Always** use the generated constants (`Method`, `EventKind`, `SubscriptionType`, `AgentStatus`, `WatchKind`, `ResultTag`), not raw strings: the types accept strings, but constants fail when herdr renames something.
+- **Always** `close()` the client (or `await using` a held connection); a leaked client keeps the socket open.
+- **Always** snapshot before you subscribe: a subscription delivers changes, not the present. `herdr.watch({ snapshot })` does snapshot, subscribe, replay and resubscribe for you.
+- **Always** pass `timeout_ms` to long-poll methods (`agent.wait`, `events.wait`, `pane.wait_for_output`): herdr would wait forever, and the types require it on `agent.wait`.
+- **Never** resend `agent.prompt` after a timeout: a timeout is not proof the prompt was not delivered.
+- **Never** assume `uint64` fields above 2^53 survive; they are JSON numbers.
+- **Never** import from the package's `dist/` or `src/` paths; only the entries above.
+- **Never** point tests at a real herdr. Use `createFakeHerdr()`.
+
+## Where to go next
+
+| Task | Read |
+|---|---|
+| Wait for an agent, prompt it, read output, split panes, subscribe, watch, test | `references/recipes.md` |
+| An error or exception, what to catch, retry or not | `references/errors.md` |
+| Which method exists, its params and result | `references/api-map.md` (namespaces and where the full list lives) |
+| Versions, upgrades, drift against the installed herdr | `references/versions.md` |
+
+## Verify
+
+Run the type checker, then the code against the fake (`references/recipes.md`, "Test it"). Only point at the real socket when the owner says so.

package/skills/herdr-sdk/references/api-map.md

@@ -0,0 +1,28 @@
+# API map
+
+The authoritative list is generated and ships with the package: `docs/api/methods.md` and `docs/api/events.md`, or in code `import { METHODS } from "@stateforge-labs/herdr-sdk/schema"`. This page only orients you.
+
+## Namespaces (method = `namespace.name`, called as `herdr.namespace.name(params)`)
+
+`pane` (35, the largest: list, get, read, split, send_text, send_keys, wait_for_output, focus, close, ...), `agent` (12: list, get, read, start, prompt, wait, send_keys, rename, view.*), `plugin` (11), `workspace` (9), `tab` (7), `server` (6), `worktree` (4), `layout` (3), `integration` (3), `client` (3), `events` (subscribe, wait), `session` (snapshot), `ping`, plus single-method namespaces (`notification`, `popup`, `command`, `held`, ...).
+
+## Capability classes (which entry has them)
+
+| Class | Meaning | Examples | Entries |
+|---|---|---|---|
+| R-meta | read structure | `*.list`, `*.get`, `session.snapshot` | all |
+| R-content | read terminal content | `pane.read`, `agent.read` | `connect`, `connectReadOnly({content:true})` |
+| W | change UI or state | `*.rename`, `*.focus`, `pane.split` | `connect`, admin |
+| I | input injection | `pane.send_text`, `agent.prompt` | `connect`, admin (prompt also `connectPrompt`) |
+| H | hook reporter | `pane.report_*` | `connect`, admin |
+| L | long-poll or stream | `agent.wait`, `events.wait`, `pane.wait_for_output`, `events.subscribe` | `connect`, admin, read-only (reads) |
+| C | connection-bound | `client.window_title.set` | via `hold()` |
+| X | spawns or executes | `agent.start`, `plugin.link`, `command.invoke` | admin only |
+| D | destructive | `*.close`, `worktree.remove` | admin only |
+| S | server control | `server.stop`, `server.reload_config` | admin only |
+
+If a method you need is not on your client, it is deliberately out of that entry's class set. Widen the entry (with a stated reason), do not cast.
+
+## Ids
+
+Panes, tabs and workspaces are addressed by their ids (`p_1`-style strings from `*.list` or the snapshot). `agent.*` methods take a `target` (agent name or id).

package/skills/herdr-sdk/references/errors.md

@@ -0,0 +1,19 @@
+# Errors
+
+Five Promise error classes, all exported from `@stateforge-labs/herdr-sdk`. Check with `instanceof`.
+
+| Class | Meaning | Fields | Retry? |
+|---|---|---|---|
+| `HerdrError` | herdr received the call and refused it (error envelope) | `code`, `method`, `body`, `message` | No: fix the params or the target |
+| `HerdrTransportError` | no usable answer: cannot connect, timeout, abort, socket closed, malformed line | `isTimeout`, `cause` | Reads: yes. `agent.prompt` and other input methods: **no**, delivery is unknown |
+| `ProtocolMismatchError` | the server speaks another protocol than this client (`connect()` default is exact) | `expected`, `actual` | No: upgrade the package or run the matching herdr |
+| `UnsupportedByServerError` | the method needs a server capability herdr did not advertise; nothing was sent | `method`, `capability` | No |
+| `SubscriptionEnded` | the server closed a subscription connection | `method` | `watch()` resubscribes for you; with raw `events.subscribe` you resubscribe yourself and re-snapshot |
+
+Notes:
+
+- `connect()` rejects when there is no socket; the message names the path. Check that herdr is running and that `HERDR_SOCKET` points at the server you mean.
+- A closed client rejects later calls with `HerdrTransportError` without contacting herdr; `close()` also ends its subscriptions, watch loops and held connections.
+- The default per-request timeout is 10 s (`timeoutMs` option). Long-poll methods add their own `timeout_ms`.
+- `onCall({ method, durationMs, outcome })` on `connect()` options is the metrics hook; `onUnknown(frame)` receives push frames of kinds this version does not know (herdr may add some): log and ignore them.
+- Effect entry: the same errors are tagged: `HerdrRefused`, `HerdrUnavailable` (transport and subscription end; `isTimeout`), `ProtocolMismatch`, `HerdrUnsupported`.

package/skills/herdr-sdk/references/recipes.md

@@ -0,0 +1,171 @@
+# Recipes
+
+Every `ts` block below is type-checked against the package by `test/skill/skill.test.ts`, and blocks marked `ts run` are executed against the fake herdr. Lines starting `// fake:` are the harness script (what the server answers); they are not part of your code. Copy them as written; `HERDR_SOCKET` or the default socket path picks the server.
+
+## List agents and what they are doing
+
+```ts run
+// fake: agent.list {"type":"agent_list","agents":[{"agent_status":"idle","focused":false,"pane_id":"p_1","revision":1,"tab_id":"t_1","terminal_id":"term_1","workspace_id":"w_1","name":"reviewer"}]}
+import { connectReadOnly } from "@stateforge-labs/herdr-sdk/read-only"
+
+const herdr = await connectReadOnly()
+const { agents } = await herdr.agent.list({})
+for (const agent of agents) console.log(agent.name, agent.agent_status, agent.pane_id)
+herdr.close()
+```
+
+## Take the present state in one call
+
+`session.snapshot` returns workspaces, tabs, panes, agents and layouts together. Prefer it to many `*.list` calls.
+
+```ts run
+// fake: session.snapshot {"type":"session_snapshot","snapshot":{"agents":[],"layouts":[],"panes":[],"protocol":22,"tabs":[],"version":"0.9.5","workspaces":[]}}
+import { connectReadOnly } from "@stateforge-labs/herdr-sdk/read-only"
+
+const herdr = await connectReadOnly()
+const { snapshot } = await herdr.session.snapshot({})
+console.log(snapshot.workspaces.length, snapshot.tabs.length, snapshot.panes.length)
+herdr.close()
+```
+
+## Wait for an agent to finish
+
+The timeout is required in practice: without it herdr waits forever.
+
+```ts run
+// fake: agent.wait {"type":"agent_info","agent":{"agent_status":"idle","focused":false,"pane_id":"p_1","revision":1,"tab_id":"t_1","terminal_id":"term_1","workspace_id":"w_1","name":"reviewer"}}
+import { connectReadOnly } from "@stateforge-labs/herdr-sdk/read-only"
+import { AgentStatus } from "@stateforge-labs/herdr-sdk"
+
+const herdr = await connectReadOnly()
+const info = await herdr.agent.wait({ target: "reviewer", until: [AgentStatus.Done], timeout_ms: 60_000 })
+console.log(info.agent.agent_status)
+herdr.close()
+```
+
+## Prompt an agent
+
+`connectPrompt()` can read structure and prompt, nothing else.
+
+```ts run
+// fake: agent.prompt {"type":"ok"}
+import { connectPrompt } from "@stateforge-labs/herdr-sdk/read-only"
+import { HerdrError, HerdrTransportError } from "@stateforge-labs/herdr-sdk"
+
+const herdr = await connectPrompt()
+try {
+  await herdr.agent.prompt({ target: "reviewer", text: "run the tests" })
+} catch (error) {
+  if (error instanceof HerdrError) console.error("refused", error.code, error.message)
+  else if (error instanceof HerdrTransportError) console.error("unknown whether delivered; do not resend blindly")
+  else throw error
+}
+herdr.close()
+```
+
+## Read a pane's terminal output
+
+Terminal content is a separate capability: `connect()` has it, `connectReadOnly()` needs `{ content: true }`.
+
+```ts run
+// fake: pane.read {"type":"pane_read","read":{"format":"text","pane_id":"p_1","revision":1,"source":"recent","tab_id":"t_1","text":"ok","truncated":false,"workspace_id":"w_1"}}
+import { connectReadOnly } from "@stateforge-labs/herdr-sdk/read-only"
+
+const herdr = await connectReadOnly({ content: true })
+const { read } = await herdr.pane.read({ pane_id: "p_1", source: "recent", lines: 40 })
+console.log(read)
+herdr.close()
+```
+
+## Wait for output to match
+
+```ts run
+// fake: pane.wait_for_output {"type":"ok"}
+import { connect } from "@stateforge-labs/herdr-sdk"
+
+const herdr = await connect()
+await herdr.pane.wait_for_output({
+  pane_id: "p_1",
+  source: "recent",
+  match: { type: "regex", value: "tests? passed" },
+  timeout_ms: 30_000,
+})
+herdr.close()
+```
+
+## Split a pane and run a command in it
+
+`pane.split` is a write (`connect()`), not available on read-only clients.
+
+```ts run
+// fake: pane.split {"type":"ok"}
+// fake: pane.send_text {"type":"ok"}
+// fake: pane.send_keys {"type":"ok"}
+import { connect } from "@stateforge-labs/herdr-sdk"
+
+const herdr = await connect()
+await herdr.pane.split({ direction: "right", target_pane_id: "p_1", cwd: "/tmp" })
+await herdr.pane.send_text({ pane_id: "p_1", text: "echo hi" })
+await herdr.pane.send_keys({ pane_id: "p_1", keys: ["Enter"] })
+herdr.close()
+```
+
+## React to events (subscribe)
+
+A subscription is an async iterable of frames. Subscribe, loop, `close()` when done.
+
+```ts run
+import { connectReadOnly } from "@stateforge-labs/herdr-sdk/read-only"
+import { EventKind, SubscriptionType } from "@stateforge-labs/herdr-sdk/read-only"
+
+const herdr = await connectReadOnly()
+const subscription = await herdr.events.subscribe([
+  { type: SubscriptionType.PaneCreated },
+  { type: SubscriptionType.PaneClosed },
+])
+const stop = setTimeout(() => subscription.close(), 50)
+for await (const frame of subscription) {
+  if (frame.event === EventKind.PaneClosed) break
+}
+clearTimeout(stop)
+subscription.close()
+herdr.close()
+```
+
+## Keep a live view (watch)
+
+`watch` takes a snapshot, subscribes, replays frames that arrived in between, and resubscribes with backoff after a drop. The first item is always `Live`. Frames can be replayed, so make your fold idempotent.
+
+```ts
+import { connectReadOnly } from "@stateforge-labs/herdr-sdk/read-only"
+import { WatchKind } from "@stateforge-labs/herdr-sdk"
+
+const herdr = await connectReadOnly()
+const view = herdr.watch({ snapshot: () => herdr.session.snapshot({}) })
+for await (const change of view) {
+  if (change.kind === WatchKind.Live) console.log("snapshot", change.snapshot.snapshot.panes.length)
+  else console.log("frame", change.frame)
+}
+```
+
+## Test it (no real herdr)
+
+The fake answers `ping`; every other method must be scripted with `fake.reply(method, result)`, otherwise herdr-style `unknown_method` is returned. It also lets you script failures, silence and pushes.
+
+```ts run
+import { connect, Method, ResultTag } from "@stateforge-labs/herdr-sdk"
+import { createFakeHerdr } from "@stateforge-labs/herdr-sdk/test-kit"
+
+const fake = await createFakeHerdr()
+fake.reply(Method.AgentList, { type: ResultTag.AgentList, agents: [] })
+const herdr = await connect({ socketPath: fake.path })
+
+const { agents } = await herdr.agent.list({})
+if (agents.length !== 0) throw new Error("expected no agents")
+if (fake.receivedMethods().join() !== [Method.Ping, Method.AgentList].join()) throw new Error("unexpected calls")
+
+herdr.close()
+await fake.stop()
+```
+
+Other fake controls: `fail(method, error)`, `silent(method)` (for timeout tests), `replySequence`, `push(frame)`, `closeSubscribers()`, `subscriberCount()`, `capabilities`, `requests()`.

package/skills/herdr-sdk/references/versions.md

@@ -0,0 +1,7 @@
+# Versions, upgrades, drift
+
+- The package version follows herdr: a protocol change, or a removed, renamed or narrowed API, is a major; added methods and events are a minor; everything else is a patch. The package.json `herdr` field has `protocol`, `schemaVersion` and `testedWith`.
+- `connect()` checks the server's protocol and rejects with `ProtocolMismatchError` unless it matches exactly (`protocolPolicy: ProtocolPolicy.Minimum` accepts a newer server).
+- The generated reference ships with the package: `docs/api/methods.md` (102 methods, params type, result tag, capability class, long-poll, server capability gate) and `docs/api/events.md` (event kinds and subscription types). Read these instead of guessing a name.
+- `herdr-drift` (bin) compares the committed schema with the installed herdr: exit 0 clean, 1 drift, 2 usage, 3 herdr not found or unreadable schema (3 means "could not look", never green).
+- When herdr upgrades: run `herdr-drift`; if only additions, bump the minor; if it reports removals, treat it as a major and re-read `docs/api/methods.md`.