@dsh-blue/herdr-agent-state 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-blue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @dsh-blue/herdr-agent-state
+
+A DeepSeek Harness (`dsh`) plugin that reports a pane's agent state — `working`,
+`blocked`, `idle` — and its session reference to [Herdr](https://herdr.dev/)
+through Herdr's pane socket integration. It lets Herdr's sidebar show where the
+agent actually is, surface waiting agents, and expose the session for restore,
+**without any change to Herdr** (Herdr's [custom integration](https://herdr.dev/docs/integrations/#integrate-your-own-agent)
+path).
+
+It works in **any dsh frontend** — TUIs, the web app, and headless — because it
+subscribes only to documented dsh extension points (agent lifecycle events, the
+approval and user-question waterfalls) and carries no UI or renderer dependency.
+
+## Install
+
+The plugin is a **dsh bundle** (`dsh.bundle.patch` → `cordis.patch.yml`), so
+`dsh plugin add` activates it automatically — no manual `cordis.patch.yml` edit:
+
+```sh
+dsh plugin --profile <profile> add @dsh-blue/herdr-agent-state
+```
+
+It inserts a row labelled `herdr-agent-state`. To change the Herdr agent label
+that a frontend reports, override the same row id in the profile's
+`cordis.patch.yml` (last write wins per row):
+
+```yaml
+plugins:
+  herdr-agent-state:
+    config:
+      agent: blue   # default dsh; this frontend's own label
+```
+
+The plugin is a strict no-op outside a Herdr pane (`HERDR_ENV=1` plus
+`HERDR_SOCKET_PATH` and `HERDR_PANE_ID` absent), so it never adds side effects
+to a normal terminal session.
+
+### Install straight from GitHub (before publishing to npm)
+
+`dsh plugin` is a thin [pnpm](https://pnpm.io/) forwarder, so it accepts any
+pnpm dependency spec — including a GitHub repo. The plugin ships plain ESM
+JavaScript with no build step, so `dsh plugin add` installs and auto-activates
+the bundle in one command with no `prepare`/`lib` and no `allowBuilds` entry:
+
+```sh
+# master branch; pin the exact commit when you want reproducibility
+dsh plugin --profile <profile> add github:dsh-blue/herdr-agent-state
+# or pinned to a commit (the pattern Blue marketplace installs use):
+dsh plugin --profile <profile> add dsh-blue/herdr-agent-state#<40-char-sha>
+```
+
+## How it reports state
+
+| Herdr state | dsh signal |
+|---|---|
+| `working` | any agent reports `agent/status = running` |
+| `blocked` | an `approval/request` or `user-questions/request` waterfall is awaiting an answer |
+| `idle` | no agent running and nothing pending |
+
+Blocked observations are **passive**: the plugin calls `await next()` and returns
+the downstream decision unchanged, so approval and question flows are never
+altered. Reports are coalesced (latest value wins) and tagged with a strictly
+increasing `seq`, mirroring Herdr's own Pi integration wire contract.
+
+The plugin releases the pane's lifecycle authority on unload and process exit,
+and re-reports on `agent/session-start` so a reload does not leave Herdr with a
+stale authority.
+
+## Configuration
+
+| Field | Default | Meaning |
+|---|---|---|
+| `agent` | `'dsh'` | Herdr agent label reported for the pane. A frontend sets its own name here. |
+| `source` | `'herdr:dsh-agent-state'` | Stable unique integration source. Keep it constant. |
+| `transport` | `'socket'` | `socket` (implemented) or `cli` (declared, not yet implemented — rejected at load). |
+| `reportSession` | `true` | Report the pane's session reference to Herdr. |
+| `message` | `'tool'` | `tool` attaches a human label to blocked reports; `none` omits it. |
+| `enabled` | `true` | Kill-switch to coexist with another reporter in the same tree. |
+
+## Version compatibility
+
+Built against the dsh `0.1.2-alpha` line. It shares the host's
+`@deepseek-ai/schemastery` instance (declared as a peer, so the runtime
+`Config` schema uses the same copy the host validates against).
+
+## Development
+
+```sh
+pnpm install
+pnpm test        # vitest run (unit + fake-socket integration)
+```
+
+The plugin ships as plain ESM JavaScript, so there is no build step. Its
+`state` and `transport` modules depend only on Node builtins, so their tests
+run without a dsh host.
+
+## License
+
+MIT.

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# The herdr-agent-state bundle patch: insert the pane-state reporter plugin
+# into the profile's layer stack. Because package.json declares
+# `dsh.bundle.patch`, `dsh plugin add` joins this bundle into the profile's
+# `dsh.profile.bundles` and activates the row automatically — no manual
+# `cordis.patch.yml` edit needed. Override a value by patching the same row id
+# from the profile layer (last write wins per row).
+- insert:
+    - id: herdr-agent-state
+      name: '@dsh-blue/herdr-agent-state'
+      config:
+        # Herdr agent label for the pane. Set a frontend's own name (e.g.
+        # `blue`) by overriding this row's `config` in the profile patch.
+        agent: dsh

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@dsh-blue/herdr-agent-state",
+  "version": "0.1.0",
+  "description": "dsh plugin: report agent state (working/blocked/idle) and session reference to Herdr via its pane socket integration. Works in any dsh profile — TUIs, web, headless.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": "^22.19 || >=24"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "cordis",
+    "plugin",
+    "herdr",
+    "agent-state",
+    "pane",
+    "integration"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/index.js

@@ -0,0 +1,137 @@
+/**
+ * Herdr agent-state reporter for any dsh frontend.
+ *
+ * A Cordis function plugin that, when loaded inside a Herdr pane, reports the
+ * pane's semantic state (working / blocked / idle) and session reference to
+ * Herdr's pane socket. It depends only on documented dsh extension points —
+ * agent lifecycle events, the approval and user-question waterfalls — so it
+ * works in TUI, web, and headless profiles alike. Outside a Herdr pane it is a
+ * strict no-op.
+ *
+ * Ships as plain ESM JavaScript (no build step) so `dsh plugin add` from a git
+ * repo loads it directly without `prepare`/`lib`.
+ *
+ * @module @dsh-blue/herdr-agent-state
+ */
+
+import z from '@deepseek-ai/schemastery'
+
+import { AgentStateModel } from './state.js'
+import { HerdrReporter, herdrEnabled } from './transport.js'
+
+export const name = 'herdr-agent-state'
+
+/** The plugin consumes no injected services; it reads the environment and events only. */
+export const inject = []
+
+/** Schemastery configuration for the plugin. */
+export const Config = z.object({
+  /**
+   * Herdr agent label reported for the pane. Defaults to `dsh`; a host frontend
+   * sets its own name (e.g. `blue`) by overriding this field in a patch overlay.
+   */
+  agent: z.string().default('dsh'),
+  /**
+   * Stable, unique integration source. Keep it constant so Herdr attributes the
+   * pane's lifecycle authority to this reporter and so a future dsh-built
+   * reporter can coexist under a different source.
+   */
+  source: z.string().default('herdr:dsh-agent-state'),
+  /**
+   * Transport to Herdr. `socket` speaks the pane socket directly; `cli` is a
+   * declared-but-unimplemented fallback and is rejected at load.
+   */
+  transport: z.union([z.const('socket'), z.const('cli')]).default('socket'),
+  /** Report the pane's session reference so Herdr can expose it for restore. */
+  reportSession: z.boolean().default(true),
+  /** Whether to attach a human label to blocked reports. */
+  message: z.union([z.const('tool'), z.const('none')]).default('tool'),
+  /** Kill-switch for coexisting with another reporter in the same tree. */
+  enabled: z.boolean().default(true),
+})
+
+/** A concise human label for the leading question in a pending request. */
+function questionLabel(questions) {
+  const item = questions[0]
+  const text = item?.title ?? item?.label ?? item?.placeholder ?? 'question'
+  return questions.length > 1 ? `${text} (+${questions.length - 1} more)` : text
+}
+
+/**
+ * Drive one pane's reporter from the live dsh event stream.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {{ agent: string, source: string, transport: 'socket' | 'cli', reportSession: boolean, message: 'tool' | 'none', enabled: boolean }} config
+ */
+export function apply(ctx, config) {
+  if (!config.enabled) return
+  if (config.transport !== 'socket') {
+    throw new Error(`herdr-agent-state: transport "${String(config.transport)}" is not implemented; use 'socket'`)
+  }
+
+  const env = process.env
+  if (!herdrEnabled(env)) return
+
+  const reporter = new HerdrReporter({
+    source: config.source,
+    agent: config.agent,
+    reportSession: config.reportSession,
+    env,
+  })
+  const model = new AgentStateModel()
+
+  const publish = (force = false) => {
+    const report = model.desired()
+    if (config.message === 'none' && report.state === 'blocked') {
+      reporter.publishState({ state: report.state }, force)
+    } else {
+      reporter.publishState(report, force)
+    }
+  }
+
+  ctx.on('agent/disposed', (payload) => {
+    model.setRunning(payload.agent, false)
+    publish()
+  })
+
+  ctx.on('agent/status', (payload) => {
+    model.setRunning(payload.agent, payload.status === 'running')
+    publish()
+  })
+
+  // Observers only: they delegate with `await next()` and never alter the
+  // downstream decision, so the approval / question flow is untouched.
+  ctx.on('approval/request', async (req, next) => {
+    model.setBlocked(true, req.reason ?? req.toolName)
+    publish()
+    try {
+      return await next()
+    } finally {
+      model.setBlocked(false)
+      publish()
+    }
+  })
+
+  ctx.on('user-questions/request', async (request, next) => {
+    model.setBlocked(true, questionLabel(request.questions))
+    publish()
+    try {
+      return await next()
+    } finally {
+      model.setBlocked(false)
+      publish()
+    }
+  })
+
+  ctx.on('agent/session-start', (payload) => {
+    reporter.setSessionId(payload.agent?.session?.header?.id ?? undefined)
+    reporter.reportSession(payload.source)
+    model.setRunning(payload.agent, false)
+    publish(true)
+  })
+
+  ctx.effect(
+    () => () => reporter.release(),
+    'herdr-agent-state: release pane lifecycle authority on unload',
+  )
+  process.once('beforeExit', () => reporter.release())
+}

package/src/state.js

@@ -0,0 +1,57 @@
+/**
+ * Pure semantic state model for the pane's Herdr state.
+ *
+ * @module @dsh-blue/herdr-agent-state/state
+ */
+
+export class AgentStateModel {
+  constructor() {
+    /** Agent objects reported as `running`, by identity (stable per session). */
+    this.runningAgents = new Set()
+    /** Number of open approval/question interactions. */
+    this.blockedCount = 0
+    /** Label of the most recently opened blocked interaction. */
+    this.blockedMessage = undefined
+  }
+
+  /**
+   * Record one agent's running state; pass the same agent object on later events.
+   * @param {unknown} agent
+   * @param {boolean} running
+   */
+  setRunning(agent, running) {
+    if (running) this.runningAgents.add(agent)
+    else this.runningAgents.delete(agent)
+  }
+
+  /**
+   * Open or close one blocked interaction. `active: true` opens a pending
+   * approval/question and records `message`; `active: false` closes the most
+   * recent one (never below zero).
+   * @param {boolean} active
+   * @param {string} [message]
+   */
+  setBlocked(active, message) {
+    if (active) {
+      this.blockedCount += 1
+      if (message !== undefined) this.blockedMessage = message
+      return
+    }
+    this.blockedCount = Math.max(0, this.blockedCount - 1)
+    if (this.blockedCount === 0) this.blockedMessage = undefined
+  }
+
+  /**
+   * The report derived from the current inputs.
+   * @returns {{ state: 'working' | 'blocked' | 'idle', message?: string }}
+   */
+  desired() {
+    if (this.blockedCount > 0) {
+      return this.blockedMessage !== undefined
+        ? { state: 'blocked', message: this.blockedMessage }
+        : { state: 'blocked' }
+    }
+    if (this.runningAgents.size > 0) return { state: 'working' }
+    return { state: 'idle' }
+  }
+}

package/src/transport.js

@@ -0,0 +1,178 @@
+/**
+ * Herdr pane socket transport and reporter.
+ *
+ * Mirrors Herdr's own bundled Pi integration wire contract: one newline-delimited
+ * JSON request per `pane.report_agent` / `pane.report_agent_session` /
+ * `pane.release_agent` call, a fresh single connection per request, a short
+ * timeout plus one longer retry, and a failure that never rejects into the host
+ * process (Herdr being absent must not disturb the dsh frontend).
+ *
+ * Only `node:net` is used.
+ * @module @dsh-blue/herdr-agent-state/transport
+ */
+
+import net from 'node:net'
+
+/** True when the process runs inside a Herdr pane that can receive reports. */
+export function herdrEnabled(env) {
+  return env.HERDR_ENV === '1' && Boolean(env.HERDR_SOCKET_PATH) && Boolean(env.HERDR_PANE_ID)
+}
+
+/** Resolve the socket endpoint, mapping Windows named pipes as Herdr does. */
+export function socketEndpoint(env) {
+  const raw = env.HERDR_SOCKET_PATH ?? ''
+  return process.platform === 'win32' && raw !== '' ? `\\\\.\\pipe\\${raw}` : raw
+}
+
+/**
+ * Deliver one request over a fresh single connection. A pane report is
+ * fire-and-forget, so delivery means the request was written to Herdr's socket
+ * (the write flushed), not that Herdr replied — Herdr's pane socket does not
+ * necessarily acknowledge. Resolves `true` once the write flushes, `false` on
+ * any failure. Never throws.
+ *
+ * @param {{ id: string, method: string, params: Record<string, unknown> }} request
+ * @param {string} endpoint
+ * @param {number} [timeoutMs]
+ * @param {number} [retryMs]
+ * @returns {Promise<boolean>}
+ */
+export function sendRequest(request, endpoint, timeoutMs = 500, retryMs = 1500) {
+  return new Promise((resolve) => {
+    const attempt = (delay, onSettled) => {
+      let finished = false
+      let timer
+      const finish = (delivered) => {
+        if (finished) return
+        finished = true
+        if (timer !== undefined) clearTimeout(timer)
+        client.destroy()
+        onSettled(delivered)
+      }
+
+      const client = net.createConnection(endpoint)
+      client.on('error', () => finish(false))
+      client.on('end', () => finish(false))
+      client.on('connect', () => {
+        client.write(`${JSON.stringify(request)}\n`, () => finish(true))
+      })
+      timer = setTimeout(() => finish(false), delay)
+      timer.unref?.()
+    }
+
+    attempt(timeoutMs, (delivered) => {
+      if (delivered) resolve(true)
+      else attempt(retryMs, (retried) => resolve(retried))
+    })
+  })
+}
+
+/**
+ * Owns the seq counter, the single-flight latest-wins state queue, the session
+ * reference, and the transport. Calling `publishState` coalesces bursts: only
+ * the newest state is sent, and only when it differs from the last sent one.
+ */
+export class HerdrReporter {
+  /**
+   * @param {{ source: string, agent: string, reportSession: boolean, env: Record<string, string | undefined> }} options
+   */
+  constructor(options) {
+    this.source = options.source
+    this.agent = options.agent
+    this.reportSessionRef = options.reportSession
+    this.endpoint = socketEndpoint(options.env)
+    this.paneId = options.env.HERDR_PANE_ID ?? ''
+    // Wall-clock base keeps seq strictly increasing across process restarts.
+    this.seq = Date.now() * 1000
+    this.sessionId = undefined
+    this.sendInFlight = false
+    this.queued = undefined
+    this.lastSent = undefined
+  }
+
+  /** Record the session reference to attach to subsequent reports. */
+  setSessionId(id) {
+    this.sessionId = id
+  }
+
+  nextSeq() {
+    this.seq += 1
+    return this.seq
+  }
+
+  sessionParams() {
+    if (this.reportSessionRef && this.sessionId !== undefined && this.sessionId !== '') {
+      return { agent_session_id: this.sessionId }
+    }
+    return {}
+  }
+
+  send(request) {
+    return sendRequest(request, this.endpoint)
+  }
+
+  /** Report the current pane state, coalescing bursts to a single latest value. */
+  publishState(report, force = false) {
+    if (!force && report.state === this.lastSent?.state && report.message === this.lastSent.message) {
+      return
+    }
+    if (!force) this.lastSent = report
+    this.queued = { ...report, seq: this.nextSeq() }
+    void this.drain()
+  }
+
+  /** Report the pane's session reference; Herdr exposes it for restore. */
+  reportSession(sessionStartSource) {
+    const params = this.sessionParams()
+    if (Object.keys(params).length === 0) return
+    void this.send({
+      id: `${this.source}:session:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+      method: 'pane.report_agent_session',
+      params: {
+        pane_id: this.paneId,
+        source: this.source,
+        agent: this.agent,
+        seq: this.nextSeq(),
+        ...(sessionStartSource !== undefined ? { session_start_source: sessionStartSource } : {}),
+        ...params,
+      },
+    })
+  }
+
+  /** Release this pane's lifecycle authority (on unload or process exit). */
+  release() {
+    void this.send({
+      id: `${this.source}:release:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+      method: 'pane.release_agent',
+      params: { pane_id: this.paneId, source: this.source, agent: this.agent },
+    })
+  }
+
+  async drain() {
+    if (this.sendInFlight) return
+    this.sendInFlight = true
+    try {
+      while (this.queued !== undefined) {
+        const next = this.queued
+        this.queued = undefined
+        const params = this.sessionParams()
+        await this.send({
+          id: `${this.source}:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+          method: 'pane.report_agent',
+          params: {
+            pane_id: this.paneId,
+            source: this.source,
+            agent: this.agent,
+            state: next.state,
+            ...(next.message !== undefined ? { message: next.message } : {}),
+            seq: next.seq,
+            ...params,
+          },
+        })
+      }
+    } finally {
+      this.sendInFlight = false
+      if (this.queued !== undefined) this.drain()
+    }
+  }
+}