@dsh-blue/herdr-agent-state 0.1.0 → 0.2.0

package/README.md

@@ -1,10 +1,12 @@
 # @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)
+`blocked`, `idle` — its session reference, and its session title (as the Herdr
+pane title) 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, name panes after the conversation, 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
@@ -21,14 +23,15 @@ 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):
+a frontend reports, patch the same row id in the profile's `cordis.patch.yml`
+(an id-targeted patch replaces that row's whole `config`; the schema defaults
+fill any field you omit):
 
 ```yaml
-plugins:
-  herdr-agent-state:
-    config:
-      agent: blue   # default dsh; this frontend's own label
+# ~/.dsh/profiles/<profile>/cordis.patch.yml
+- id: 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
@@ -66,16 +69,118 @@ 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.
 
+## How it reports the title
+
+The plugin mirrors the dsh session title — the first-prompt fallback, the
+LLM-generated refinement, or a title pinned with `/rename` — as the Herdr pane
+title through Herdr's display-only `pane.report_metadata` channel:
+
+- Titles are observed on the same `session/title` session-log feed the dsh TUI
+  itself renders, filtered to the session the pane's agent is currently
+  running (subagent sessions in the same process are skipped).
+- A resumed session's existing title is read directly at `agent/session-start`
+  (past title events are replay seeds that never re-enter the live feed), so a
+  restored pane is named immediately.
+- The report carries the same `source` and `agent` as the state reports plus
+  an `applies_to_source` guard, so the title is accepted exactly while this
+  reporter holds the pane's lifecycle authority. Herdr checks that guard when
+  the report arrives (not continuously), so the reporter also clears the title
+  when it releases the pane's authority. A title never affects waits,
+  notifications, or rollups, and is not restored across a Herdr server
+  restart.
+- Herdr trims and caps the text; after a `/clear` the previous title stays
+  until the new session produces its first title (usually seconds).
+
 ## 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. |
+### Configuration reference
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `agent` | string | `'dsh'` | The Herdr agent label reported for the pane. Set a frontend's own name (e.g. `blue`) so Herdr's sidebar groups it under that label. |
+| `source` | string | `'herdr:dsh-agent-state'` | Stable, unique integration source. Herdr attributes the pane's lifecycle authority to this source. **Keep it constant.** Changing it makes Herdr treat the pane as a *different* authority mid-session. |
+| `transport` | `'socket'` \| `'cli'` | `'socket'` | How to report to Herdr. Only `socket` is implemented (speaks the pane socket directly). `cli` is declared but not yet implemented — it throws **at load**, so don't set it. |
+| `reportSession` | boolean | `true` | Report the pane's session reference (`agent_session_id`) so Herdr can expose it for restore. Set `false` to suppress session reporting. |
+| `title` | `'session'` \| `'none'` | `'session'` | Which title to publish as the Herdr pane title (display-only metadata). `session` mirrors the dsh session title — first-prompt fallback, LLM-generated, or pinned by `/rename`; `none` disables title reporting. |
+| `message` | `'tool'` \| `'none'` | `'tool'` | Whether to attach a human label to `blocked` reports. `tool` sends the tool name / question summary; `none` sends `blocked` with no message. |
+| `enabled` | boolean | `true` | Kill-switch. Set `false` to disable the reporter in this tree — useful to coexist with another reporter. |
+
+### How to configure it
+
+The plugin is a bundle row labelled `herdr-agent-state`, so it is inserted
+automatically when you `dsh plugin add`. Because its `Config` schema gives every
+field a default, you only set what you want to change; the schema fills the
+rest. A profile's `cordis.patch.yml` is a **top-level YAML array of loader patch
+entries**, so you target the row by `id` and replace its `config`:
+
+```yaml
+# ~/.dsh/profiles/<profile>/cordis.patch.yml
+- id: herdr-agent-state
+  config:
+    agent: blue
+```
+
+The patch replaces the row's whole `config`, so the schema defaults supply any
+field you don't set. Include `name` as a guard — if it ever mismatches the row,
+the patch is skipped with a warning instead of silently applying:
+
+```yaml
+- id: herdr-agent-state
+  name: '@dsh-blue/herdr-agent-state'
+  config:
+    agent: blue
+    source: herdr:dsh-agent-state
+    transport: socket
+    reportSession: true
+    title: session
+    message: tool
+    enabled: true
+```
+
+### Examples
+
+Set the Herdr label to `blue` when Blue hosts the pane (all other fields
+default):
+
+```yaml
+- id: herdr-agent-state
+  config:
+    agent: blue
+```
+
+Disable session reporting and verbose blocked messages:
+
+```yaml
+- id: herdr-agent-state
+  config:
+    reportSession: false
+    message: none
+```
+
+Disable title reporting (keep state and session reports):
+
+```yaml
+- id: herdr-agent-state
+  config:
+    title: none
+```
+
+### Notes
+
+- **Changing `source`** re-attributes the pane's authority in Herdr. Keep it at
+  the default unless you are deliberately running two reporters in the same
+  tree — then give each a distinct `source`, and use `enabled: false` on the one
+  you want silent.
+- **`transport: 'cli'` is not implemented.** Setting it throws during plugin
+  load (fail-fast), so leave it as `socket`.
+- **`config` is validated** against the schemastery schema at load; an invalid
+  value (for example a `transport` that isn't `socket`/`cli`) is rejected, and
+  the plugin fails to load rather than running half-configured.
+- The pane title rides the same `source` and `agent` guards as the state
+  reports; changing `source` mid-session affects the title the same way it
+  affects lifecycle authority.
+- Because a patch replaces the row's whole `config`, any field you don't set
+  comes from the schema default — you do not need to copy every field.
 
 ## Version compatibility
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-blue/herdr-agent-state",
-  "version": "0.1.0",
+  "version": "0.2.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",

package/src/index.js

@@ -2,11 +2,12 @@
  * 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.
+ * pane's semantic state (working / blocked / idle), session reference, and
+ * session title (as the Herdr pane title) to Herdr's pane socket. It depends
+ * only on documented dsh extension points — agent lifecycle events, the
+ * approval and user-question waterfalls, and the session-log event feed — 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`.
@@ -16,7 +17,7 @@
 
 import z from '@deepseek-ai/schemastery'
 
-import { AgentStateModel } from './state.js'
+import { AgentStateModel, SessionTitleModel } from './state.js'
 import { HerdrReporter, herdrEnabled } from './transport.js'
 
 export const name = 'herdr-agent-state'
@@ -44,6 +45,12 @@ export const Config = z.object({
   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),
+  /**
+   * Which title to publish as the Herdr pane title (display-only metadata).
+   * `session` mirrors the dsh session title — first-prompt fallback,
+   * LLM-generated, or pinned by `/rename`; `none` disables title reporting.
+   */
+  title: z.union([z.const('session'), z.const('none')]).default('session'),
   /** 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. */
@@ -60,7 +67,7 @@ function questionLabel(questions) {
 /**
  * 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
+ * @param {{ agent: string, source: string, transport: 'socket' | 'cli', reportSession: boolean, title: 'session' | 'none', message: 'tool' | 'none', enabled: boolean }} config
  */
 export function apply(ctx, config) {
   if (!config.enabled) return
@@ -75,9 +82,11 @@ export function apply(ctx, config) {
     source: config.source,
     agent: config.agent,
     reportSession: config.reportSession,
+    reportTitle: config.title !== 'none',
     env,
   })
   const model = new AgentStateModel()
+  const titleModel = new SessionTitleModel()
 
   const publish = (force = false) => {
     const report = model.desired()
@@ -123,12 +132,33 @@ export function apply(ctx, config) {
   })
 
   ctx.on('agent/session-start', (payload) => {
-    reporter.setSessionId(payload.agent?.session?.header?.id ?? undefined)
+    const session = payload.agent?.session
+    const sessionId = session?.header?.id ?? undefined
+    reporter.setSessionId(sessionId)
     reporter.reportSession(payload.source)
+    // A resumed session's past titles are constructor-seed log events that
+    // never reach the session/event feed, so read the current one directly.
+    let initialTitle
+    try {
+      initialTitle = ctx.get('sessionTitle')?.get(session)?.title
+    } catch {
+      // Service not mounted or session not live: the feed covers the rest.
+    }
+    reporter.reportTitle(titleModel.setSession(sessionId, initialTitle))
     model.setRunning(payload.agent, false)
     publish(true)
   })
 
+  // Post-commit feed of appended session-log events; keep only title commits
+  // for the tracked session (child/subagent sessions in this process are
+  // skipped by the session-id match inside the model).
+  ctx.on('session/event', (session, event) => {
+    if (event.type !== 'session/title') return
+    const title = event.data?.title
+    if (typeof title !== 'string') return
+    reporter.reportTitle(titleModel.observeTitle(session?.header?.id ?? session?.id, title))
+  })
+
   ctx.effect(
     () => () => reporter.release(),
     'herdr-agent-state: release pane lifecycle authority on unload',

package/src/state.js

@@ -55,3 +55,66 @@ export class AgentStateModel {
     return { state: 'idle' }
   }
 }
+
+/**
+ * Tracks which session's title is current and the latest applicable title,
+ * deciding when a title observation should be published.
+ */
+export class SessionTitleModel {
+  constructor() {
+    /** Session identity from the latest agent/session-start. */
+    this.sessionId = undefined
+    /** Latest applicable title for that session. */
+    this.title = undefined
+    /** Last title this model told the caller to publish (change tracking). */
+    this.lastReported = undefined
+  }
+
+  /**
+   * The tracked session changed (agent/session-start). Adopts the new identity
+   * and any pre-existing title (a resumed session's title predates the plugin),
+   * resetting change tracking so an identical title re-publishes.
+   * @param {string | undefined} sessionId
+   * @param {string | undefined} [initialTitle]
+   * @returns {string | undefined} the title to publish now, if any
+   */
+  setSession(sessionId, initialTitle) {
+    this.sessionId = sessionId
+    this.title = initialTitle
+    this.lastReported = undefined
+    return this.takePublishable()
+  }
+
+  /**
+   * One session/title observation from the session/event firehose. Ignores
+   * other sessions' titles and unchanged text; adopts the first observed
+   * session when none was recorded (plugin reloaded mid-session).
+   * @param {string | undefined} sessionId
+   * @param {string} title
+   * @returns {string | undefined} the title to publish now, if changed
+   */
+  observeTitle(sessionId, title) {
+    if (this.sessionId === undefined) this.sessionId = sessionId
+    if (sessionId === undefined || sessionId !== this.sessionId) return undefined
+    this.title = title
+    return this.takePublishable()
+  }
+
+  /**
+   * The report derived from the current inputs.
+   * @returns {{ title: string } | undefined}
+   */
+  desired() {
+    return typeof this.title === 'string' && this.title.trim() !== ''
+      ? { title: this.title }
+      : undefined
+  }
+
+  /** Consume the desired report once, tracking it as reported. */
+  takePublishable() {
+    const report = this.desired()
+    if (report === undefined || report.title === this.lastReported) return undefined
+    this.lastReported = report.title
+    return report.title
+  }
+}

package/src/transport.js

@@ -3,9 +3,10 @@
  *
  * 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).
+ * `pane.release_agent` call — plus the display-only `pane.report_metadata` for
+ * the pane title — 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
@@ -74,12 +75,13 @@ export function sendRequest(request, endpoint, timeoutMs = 500, retryMs = 1500)
  */
 export class HerdrReporter {
   /**
-   * @param {{ source: string, agent: string, reportSession: boolean, env: Record<string, string | undefined> }} options
+   * @param {{ source: string, agent: string, reportSession: boolean, reportTitle?: boolean, env: Record<string, string | undefined> }} options
    */
   constructor(options) {
     this.source = options.source
     this.agent = options.agent
     this.reportSessionRef = options.reportSession
+    this.reportTitleRef = options.reportTitle ?? false
     this.endpoint = socketEndpoint(options.env)
     this.paneId = options.env.HERDR_PANE_ID ?? ''
     // Wall-clock base keeps seq strictly increasing across process restarts.
@@ -88,6 +90,7 @@ export class HerdrReporter {
     this.sendInFlight = false
     this.queued = undefined
     this.lastSent = undefined
+    this.lastSentTitle = undefined
   }
 
   /** Record the session reference to attach to subsequent reports. */
@@ -139,8 +142,51 @@ export class HerdrReporter {
     })
   }
 
-  /** Release this pane's lifecycle authority (on unload or process exit). */
+  /**
+   * Report the dsh session title as display-only Herdr pane metadata. The
+   * `agent` and `applies_to_source` guards scope the report to exactly the
+   * moments this reporter holds the pane's lifecycle authority; `release()`
+   * clears the title explicitly when that authority is given up.
+   * @param {string | undefined} title
+   */
+  reportTitle(title) {
+    if (!this.reportTitleRef) return
+    if (typeof title !== 'string' || title.trim() === '') return
+    if (title === this.lastSentTitle) return
+    this.lastSentTitle = title
+    void this.send({
+      id: `${this.source}:title:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+      method: 'pane.report_metadata',
+      params: {
+        pane_id: this.paneId,
+        source: this.source,
+        agent: this.agent,
+        applies_to_source: this.source,
+        title,
+        seq: this.nextSeq(),
+      },
+    })
+  }
+
+  /**
+   * Release this pane's lifecycle authority (on unload or process exit). The
+   * guard on a reported title is checked at acceptance time, not continuously,
+   * so a title this reporter set is cleared explicitly alongside the release.
+   */
   release() {
+    if (this.reportTitleRef && this.lastSentTitle !== undefined) {
+      this.lastSentTitle = undefined
+      void this.send({
+        id: `${this.source}:title-clear:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+        method: 'pane.report_metadata',
+        params: {
+          pane_id: this.paneId,
+          source: this.source,
+          clear_title: true,
+          seq: this.nextSeq(),
+        },
+      })
+    }
     void this.send({
       id: `${this.source}:release:${Date.now()}:${Math.random().toString(36).slice(2)}`,
       method: 'pane.release_agent',