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

package/README.md

@@ -1,10 +1,13 @@
 # @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`, labeled with the currently-executing tool while working — its
+session reference and log path, and its session display facts (title, model,
+and context usage as pane metadata) 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 +24,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
@@ -57,6 +61,13 @@ dsh plugin --profile <profile> add dsh-blue/herdr-agent-state#<40-char-sha>
 | `blocked` | an `approval/request` or `user-questions/request` waterfall is awaiting an answer |
 | `idle` | no agent running and nothing pending |
 
+While working, the pane report carries a `message` naming the
+currently-executing tool (observed on the `tools/execute` waterfall, which
+fires only for calls that survived approval — denied calls never label). The
+session reference carries both `agent_session_id` and, when the profile
+persists sessions as jsonl, `agent_session_path` (the absolute log path);
+sqlite or no-persistence backends omit the path.
+
 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
@@ -66,16 +77,161 @@ 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 metadata
+
+All display-only extras ride Herdr's `pane.report_metadata` channel. Title and
+state labels are presentation fields guarded by the same `source`/`agent` as
+the state reports plus an `applies_to_source` guard, so they apply exactly
+while this reporter holds the pane's lifecycle authority; tokens always apply
+and are this reporter's to clear. Herdr checks the guards when a report
+arrives (not continuously), so the reporter clears everything it sent when it
+releases the pane's authority. Metadata never affects waits, notifications, or
+rollups, and is not restored across a Herdr server restart.
+
+- **Title** (`title: session`) mirrors the dsh session title — first-prompt
+  fallback, LLM-generated refinement, or pinned by `/rename`. Titles are
+  observed on the same `session/title` session-log feed the dsh TUI renders,
+  filtered to the session the pane's agent is running (subagent sessions in
+  the same process are skipped); a resumed session's existing title is read
+  directly at `agent/session-start`, since past title events are replay seeds
+  that never re-enter the live feed. After a `/clear` the previous title stays
+  until the new session produces its first title (usually seconds).
+- **Tokens** (`tokens: auto`) report `model` (the raw model id) and `ctx`
+  (context occupancy, `used/window` mirroring the dsh TUI status bar, e.g.
+  `34k/1.0M`; bare `used` when the route's context window is unknown). Model
+  and window come from the `request/header` / `request/context` log events and
+  update on every assistant step's usage; a resumed session seeds all three
+  from the replayed log. Herdr's Agent sidebar can render them as `$model`
+  and `$ctx`. Tokens are cleared on release.
+- **State labels** (`stateLabels`) override the visible text per Herdr state —
+  for example `{ working: 工作中, blocked: 等待确认 }`. Non-blank entries are
+  sent once per session start and cleared on release.
+- **Working message** (`workingMessage: tool`) attaches the
+  currently-executing tool name to `working` state reports (see above);
+  blocked labels are unchanged and still governed by `message`.
+
 ## 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. |
+| `workingMessage` | `'tool'` \| `'none'` | `'tool'` | Whether to attach the currently-executing tool name to `working` reports. |
+| `tokens` | `'auto'` \| `'none'` | `'auto'` | Report the `model` and `ctx` (context usage `used/window`) tokens as Herdr Agent-sidebar metadata. `none` disables. |
+| `stateLabels` | `{ idle?, working?, blocked?, done?, unknown? }` | `{}` | Display text per Herdr state; non-blank entries are sent as pane state labels. |
+| `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
+    workingMessage: tool
+    tokens: auto
+    stateLabels:
+      idle: ''
+      working: ''
+      blocked: ''
+      done: ''
+      unknown: ''
+    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
+```
+
+Localize the Herdr state display (state labels):
+
+```yaml
+- id: herdr-agent-state
+  config:
+    stateLabels:
+      working: 工作中
+      blocked: 等待确认
+      idle: 空闲
+      done: 已完成
+```
+
+Turn off the sidebar tokens while keeping the title:
+
+```yaml
+- id: herdr-agent-state
+  config:
+    tokens: 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 and state labels ride the same `source` and `agent` guards as
+  the state reports; changing `source` mid-session affects them the same way
+  it affects lifecycle authority. Tokens are not guarded — they always apply —
+  so this reporter clears them on release.
+- 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,7 +1,7 @@
 {
   "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.",
+  "version": "0.3.0",
+  "description": "dsh plugin: report agent state (working/blocked/idle, labeled with the current tool), session reference and log path, and session metadata (title, model, context-usage tokens, state labels) to Herdr via its pane socket integration. Works in any dsh profile — TUIs, web, headless.",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/index.js

@@ -2,11 +2,13 @@
  * 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, labeled with the current
+ * tool while working), session reference and log path, and session display
+ * facts — title, model, and context usage as pane metadata — to Herdr's pane
+ * socket. It depends only on documented dsh extension points — agent lifecycle
+ * events, the approval / user-question / tool-dispatch 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 +18,7 @@
 
 import z from '@deepseek-ai/schemastery'
 
-import { AgentStateModel } from './state.js'
+import { AgentStateModel, SessionFactsModel, stateLabelsPayload, sumUsageTokens } from './state.js'
 import { HerdrReporter, herdrEnabled } from './transport.js'
 
 export const name = 'herdr-agent-state'
@@ -44,8 +46,32 @@ 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'),
+  /** Whether to attach the currently-executing tool name to working reports. */
+  workingMessage: z.union([z.const('tool'), z.const('none')]).default('tool'),
+  /**
+   * Report the model id (`model`) and context usage (`ctx`, `used/window`
+   * mirroring the dsh TUI status bar) as Herdr Agent-sidebar tokens.
+   */
+  tokens: z.union([z.const('auto'), z.const('none')]).default('auto'),
+  /**
+   * Display text per Herdr state; non-blank entries become pane state labels
+   * (e.g. `{ working: 工作中, blocked: 等待确认 }`). All-blank disables them.
+   */
+  stateLabels: z.object({
+    idle: z.string().default(''),
+    working: z.string().default(''),
+    blocked: z.string().default(''),
+    done: z.string().default(''),
+    unknown: z.string().default(''),
+  }).default({}),
   /** Kill-switch for coexisting with another reporter in the same tree. */
   enabled: z.boolean().default(true),
 })
@@ -57,10 +83,34 @@ function questionLabel(questions) {
   return questions.length > 1 ? `${text} (+${questions.length - 1} more)` : text
 }
 
+/**
+ * Seed model / context window / context occupancy from the replayed session
+ * log. A resumed session's past events are constructor seeds that never re-fire
+ * on the live session/event feed, so the initial facts come from the log.
+ * @param {unknown} session
+ * @returns {{ model?: string, contextWindow?: number, usedTokens?: number }}
+ */
+function seedSessionFacts(session) {
+  try {
+    const events = session?.events
+    if (!Array.isArray(events)) return {}
+    const model = events.findLast((e) => e.type === 'request/header')?.data?.header?.config?.model
+    const context = events.findLast((e) => e.type === 'request/context')?.data
+    const used = sumUsageTokens(events.findLast((e) => e.type === 'assistant/message')?.data?.usage)
+    return {
+      ...(typeof model === 'string' && model !== '' ? { model } : {}),
+      ...(Number.isFinite(context?.contextWindow) ? { contextWindow: context.contextWindow } : {}),
+      ...(used !== undefined ? { usedTokens: used } : {}),
+    }
+  } catch {
+    return {}
+  }
+}
+
 /**
  * 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', workingMessage: 'tool' | 'none', tokens: 'auto' | 'none', stateLabels: Record<string, string>, enabled: boolean }} config
  */
 export function apply(ctx, config) {
   if (!config.enabled) return
@@ -75,13 +125,19 @@ export function apply(ctx, config) {
     source: config.source,
     agent: config.agent,
     reportSession: config.reportSession,
+    reportTitle: config.title !== 'none',
+    reportTokens: config.tokens !== 'none',
     env,
   })
   const model = new AgentStateModel()
+  const factsModel = new SessionFactsModel()
+  const stateLabels = stateLabelsPayload(config.stateLabels)
 
   const publish = (force = false) => {
     const report = model.desired()
-    if (config.message === 'none' && report.state === 'blocked') {
+    if (report.state === 'blocked' && config.message === 'none') {
+      reporter.publishState({ state: report.state }, force)
+    } else if (report.state === 'working' && config.workingMessage === 'none') {
       reporter.publishState({ state: report.state }, force)
     } else {
       reporter.publishState(report, force)
@@ -99,7 +155,7 @@ export function apply(ctx, config) {
   })
 
   // Observers only: they delegate with `await next()` and never alter the
-  // downstream decision, so the approval / question flow is untouched.
+  // downstream decision, so the approval / question / tool flows are untouched.
   ctx.on('approval/request', async (req, next) => {
     model.setBlocked(true, req.reason ?? req.toolName)
     publish()
@@ -122,11 +178,75 @@ export function apply(ctx, config) {
     }
   })
 
+  // The dispatch waterfall fires only for calls that survived approval, so the
+  // label names a tool that is really about to run; tools/result (and the
+  // finally below) close it by call id.
+  ctx.on('tools/execute', async (exec, next) => {
+    model.toolStarted(exec.callId, exec.name)
+    publish()
+    try {
+      return await next()
+    } finally {
+      model.toolFinished(exec.callId)
+      publish()
+    }
+  })
+
+  ctx.on('tools/result', (exec) => {
+    model.toolFinished(exec.callId)
+    publish()
+  })
+
+  // Post-commit feed of appended session-log events; the facts model keeps
+  // only title / model / context commits for the tracked session (child and
+  // subagent sessions in this process are skipped by the session-id match).
+  ctx.on('session/event', (session, event) => {
+    switch (event?.type) {
+      case 'session/title':
+      case 'request/header':
+      case 'request/context':
+      case 'assistant/message':
+        break
+      default:
+        return
+    }
+    reporter.reportMetadata(factsModel.observeEvent(session?.header?.id ?? session?.id, event))
+  })
+
   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)
+
+    // Absolute jsonl log path, when a locating persistence backend is mounted.
+    let sessionPath
+    try {
+      const located = ctx.get('sessionPersistence')?.locate(session?.header)
+      if (located?.kind === 'jsonl' && typeof located.path === 'string' && located.path !== '') {
+        sessionPath = located.path
+      }
+    } catch {
+      // Service not mounted in this host: the session id still reports.
+    }
+    reporter.setSessionPath(sessionPath)
+
     reporter.reportSession(payload.source)
     model.setRunning(payload.agent, false)
     publish(true)
+
+    // Initial display facts: the title via the title service, the rest seeded
+    // from the replayed log; static state labels ride the same request. Sent
+    // after publish(true) so the authority claim precedes the guarded fields.
+    let initialTitle
+    try {
+      initialTitle = ctx.get('sessionTitle')?.get(session)?.title
+    } catch {
+      // Service not mounted or session not live: the feed covers the rest.
+    }
+    reporter.reportMetadata({
+      ...factsModel.setSession(sessionId, { title: initialTitle, ...seedSessionFacts(session) }),
+      ...(stateLabels !== undefined ? { state_labels: stateLabels } : {}),
+    })
   })
 
   ctx.effect(

package/src/state.js

@@ -1,9 +1,72 @@
 /**
- * Pure semantic state model for the pane's Herdr state.
+ * Pure models for the pane's Herdr reports: the semantic agent state, the
+ * session display facts (title, model, context), and the small formatting
+ * helpers they share.
  *
  * @module @dsh-blue/herdr-agent-state/state
  */
 
+/**
+ * Compact token count like the dsh TUI's status bar: `988`, `3.4k`, `12k`,
+ * `1.0M`. Negative values clamp to zero.
+ * @param {number} count
+ * @returns {string}
+ */
+export function formatTokens(count) {
+  const value = Math.max(0, Math.round(count))
+  if (value < 1000) return String(value)
+  if (value < 10000) return `${(value / 1000).toFixed(1)}k`
+  if (value < 1000000) return `${Math.round(value / 1000)}k`
+  if (value < 10000000) return `${(value / 1000000).toFixed(1)}M`
+  return `${Math.round(value / 1000000)}M`
+}
+
+/**
+ * Context occupancy from one `assistant/message` usage payload. The counts are
+ * disjoint, so occupancy is the uncached input plus both cache fields.
+ * `inputTokens` is the anchor: a sample without it carries no meaning.
+ * @param {{ inputTokens?: number, cacheReadTokens?: number, cacheWriteTokens?: number } | undefined} usage
+ * @returns {number | undefined}
+ */
+export function sumUsageTokens(usage) {
+  if (typeof usage?.inputTokens !== 'number') return undefined
+  return usage.inputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0)
+}
+
+/**
+ * The `used/window` context display, mirroring the dsh TUI status bar
+ * (`34k/1.0M`). Bare `used` when the window is unknown; nothing before the
+ * first usage sample.
+ * @param {number | undefined} used
+ * @param {number | undefined} contextWindow
+ * @returns {string | undefined}
+ */
+export function formatContextUsage(used, contextWindow) {
+  if (used === undefined) return undefined
+  if (!Number.isFinite(contextWindow)) return formatTokens(used)
+  return `${formatTokens(used)}/${formatTokens(contextWindow)}`
+}
+
+/** The state-label keys Herdr accepts on pane metadata. */
+const STATE_LABEL_KEYS = ['idle', 'working', 'blocked', 'done', 'unknown']
+
+/**
+ * Keep only the five known state-label keys with non-blank text, trimmed.
+ * @param {Record<string, string> | undefined} labels
+ * @returns {Record<string, string> | undefined} undefined when nothing survives
+ */
+export function stateLabelsPayload(labels) {
+  const payload = {}
+  for (const key of STATE_LABEL_KEYS) {
+    const value = labels?.[key]
+    if (typeof value === 'string' && value.trim() !== '') payload[key] = value.trim()
+  }
+  return Object.keys(payload).length > 0 ? payload : undefined
+}
+
+/**
+ * Pure semantic state model for the pane's Herdr state.
+ */
 export class AgentStateModel {
   constructor() {
     /** Agent objects reported as `running`, by identity (stable per session). */
@@ -12,6 +75,8 @@ export class AgentStateModel {
     this.blockedCount = 0
     /** Label of the most recently opened blocked interaction. */
     this.blockedMessage = undefined
+    /** Tool calls that survived approval and are still running, by call id. */
+    this.tools = new Map()
   }
 
   /**
@@ -42,7 +107,33 @@ export class AgentStateModel {
   }
 
   /**
-   * The report derived from the current inputs.
+   * A tool call survived approval and is about to run (`tools/execute`).
+   * @param {string} callId
+   * @param {string} name
+   */
+  toolStarted(callId, name) {
+    this.tools.set(callId, name)
+  }
+
+  /**
+   * The call settled (`tools/result`, or the execute waterfall's finally).
+   * Idempotent; an unknown call id is a no-op.
+   * @param {string} callId
+   */
+  toolFinished(callId) {
+    this.tools.delete(callId)
+  }
+
+  /** The most recently started still-active tool name, or undefined. */
+  currentTool() {
+    const names = [...this.tools.values()]
+    return names.length > 0 ? names[names.length - 1] : undefined
+  }
+
+  /**
+   * The report derived from the current inputs. A blocked interaction labels
+   * itself; a working pane labels itself with the current tool, when one is
+   * active.
    * @returns {{ state: 'working' | 'blocked' | 'idle', message?: string }}
    */
   desired() {
@@ -51,7 +142,154 @@ export class AgentStateModel {
         ? { state: 'blocked', message: this.blockedMessage }
         : { state: 'blocked' }
     }
-    if (this.runningAgents.size > 0) return { state: 'working' }
+    if (this.runningAgents.size > 0) {
+      const tool = this.currentTool()
+      return tool !== undefined ? { state: 'working', message: tool } : { state: 'working' }
+    }
     return { state: 'idle' }
   }
 }
+
+/** The token keys this integration reports. */
+const TOKEN_KEYS = ['model', 'ctx']
+
+/** Shallow, undefined-tolerant equality for the small token/label payloads. */
+function shallowEqual(a, b) {
+  if (a === b) return true
+  if (a === undefined || b === undefined) return false
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)])
+  for (const key of keys) {
+    if ((a[key] ?? undefined) !== (b[key] ?? undefined)) return false
+  }
+  return true
+}
+
+/**
+ * Tracks which session's display facts are current — title, model, context
+ * window, context occupancy — and decides, from session-start seeds and the
+ * session-log feed, what changed enough to publish.
+ */
+export class SessionFactsModel {
+  constructor() {
+    /** Session identity from the latest agent/session-start. */
+    this.sessionId = undefined
+    /** Latest applicable title for that session. */
+    this.title = undefined
+    /** Latest model id from request/header config. */
+    this.model = undefined
+    /** Advertised context window in tokens, when known. */
+    this.contextWindow = undefined
+    /** Context occupancy from the latest assistant/message usage sample. */
+    this.usedTokens = undefined
+    /** Last title this model published (change tracking; resets per session). */
+    this.lastReportedTitle = undefined
+    /**
+     * Last tokens snapshot this model published against (present-only). Kept
+     * across sessions so a key that becomes unknown is null-cleared rather
+     * than left stale on the pane.
+     */
+    this.lastReportedTokens = undefined
+  }
+
+  /**
+   * The tracked session changed (agent/session-start). Adopts the new identity
+   * and any pre-existing facts — a resumed session's log predates the plugin.
+   * Title change tracking resets so an identical title re-publishes; token
+   * tracking persists so stale keys are null-cleared.
+   * @param {string | undefined} sessionId
+   * @param {{ title?: string, model?: string, contextWindow?: number, usedTokens?: number }} [initial]
+   * @returns {{ title?: string, tokens?: Record<string, string | null> } | undefined}
+   */
+  setSession(sessionId, initial = {}) {
+    this.sessionId = sessionId
+    this.title = initial?.title
+    this.model = typeof initial?.model === 'string' && initial.model !== '' ? initial.model : undefined
+    this.contextWindow = Number.isFinite(initial?.contextWindow) ? initial.contextWindow : undefined
+    this.usedTokens = Number.isFinite(initial?.usedTokens) ? initial.usedTokens : undefined
+    this.lastReportedTitle = undefined
+    return this.takePublishable()
+  }
+
+  /**
+   * Fold one session/event feed observation for the tracked session. Handles
+   * `session/title`, `request/header`, `request/context`, and
+   * `assistant/message`; other types and other sessions are ignored, and the
+   * first observed session is adopted when none was recorded (plugin reloaded
+   * mid-session). A usage-less assistant/message keeps the last occupancy.
+   * @param {string | undefined} sessionId
+   * @param {{ type: string, data?: unknown }} event
+   * @returns {{ title?: string, tokens?: Record<string, string | null> } | undefined}
+   */
+  observeEvent(sessionId, event) {
+    if (this.sessionId === undefined) this.sessionId = sessionId
+    if (sessionId === undefined || sessionId !== this.sessionId) return undefined
+    switch (event?.type) {
+      case 'session/title': {
+        const title = event.data?.title
+        if (typeof title === 'string') this.title = title
+        break
+      }
+      case 'request/header': {
+        const model = event.data?.header?.config?.model
+        if (typeof model === 'string' && model !== '') this.model = model
+        break
+      }
+      case 'request/context': {
+        const window = event.data?.contextWindow
+        this.contextWindow = Number.isFinite(window) ? window : undefined
+        break
+      }
+      case 'assistant/message': {
+        const used = sumUsageTokens(event.data?.usage)
+        if (used !== undefined) this.usedTokens = used
+        break
+      }
+      default:
+        return undefined
+    }
+    return this.takePublishable()
+  }
+
+  /** The publishable title, when it is a non-blank string. */
+  desiredTitle() {
+    return typeof this.title === 'string' && this.title.trim() !== '' ? this.title : undefined
+  }
+
+  /** The publishable tokens snapshot, present-only. */
+  desiredTokens() {
+    const tokens = {}
+    if (this.model !== undefined) tokens.model = this.model
+    const ctx = formatContextUsage(this.usedTokens, this.contextWindow)
+    if (ctx !== undefined) tokens.ctx = ctx
+    return tokens
+  }
+
+  /**
+   * Consume the changed facts once, tracking them as reported. Token payloads
+   * are key-level patches: a fresh value is sent as-is, a key that became
+   * unknown after being reported is sent as null (explicit clear), and a key
+   * never reported is omitted.
+   * @returns {{ title?: string, tokens?: Record<string, string | null> } | undefined}
+   */
+  takePublishable() {
+    const out = {}
+    const title = this.desiredTitle()
+    if (title !== undefined && title !== this.lastReportedTitle) {
+      this.lastReportedTitle = title
+      out.title = title
+    }
+    const current = this.desiredTokens()
+    if (!shallowEqual(current, this.lastReportedTokens)) {
+      const payload = {}
+      for (const key of TOKEN_KEYS) {
+        if (current[key] !== undefined) payload[key] = current[key]
+        else if (this.lastReportedTokens?.[key] !== undefined) payload[key] = null
+      }
+      if (Object.keys(payload).length > 0) {
+        this.lastReportedTokens = current
+        out.tokens = payload
+      }
+    }
+    return Object.keys(out).length > 0 ? out : undefined
+  }
+}

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 display-only `pane.report_metadata` for the
+ * pane title, tokens, and state labels — 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
@@ -24,6 +25,22 @@ export function socketEndpoint(env) {
   return process.platform === 'win32' && raw !== '' ? `\\\\.\\pipe\\${raw}` : raw
 }
 
+/** Shallow, undefined-tolerant equality for the small metadata payloads. */
+function shallowEqual(a, b) {
+  if (a === b) return true
+  if (a === undefined || b === undefined) return false
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)])
+  for (const key of keys) {
+    if ((a[key] ?? undefined) !== (b[key] ?? undefined)) return false
+  }
+  return true
+}
+
+/** A fresh per-request id that stays unique across bursts. */
+function requestId(prefix) {
+  return `${prefix}:${Date.now()}:${Math.random().toString(36).slice(2)}`
+}
+
 /**
  * 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
@@ -71,23 +88,33 @@ export function sendRequest(request, endpoint, timeoutMs = 500, retryMs = 1500)
  * 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.
+ * Metadata (`reportMetadata`) is per-kind deduped and sent directly, like the
+ * session report: these values change rarely and never need burst coalescing.
  */
 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, reportTokens?: 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.reportTokensRef = options.reportTokens ?? false
     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.sessionPath = undefined
     this.sendInFlight = false
     this.queued = undefined
     this.lastSent = undefined
+    this.lastSentTitle = undefined
+    this.lastSentTokens = undefined
+    this.lastSentStateLabels = undefined
+    /** Token keys ever sent, so release() can clear exactly those. */
+    this.sentTokenKeys = new Set()
   }
 
   /** Record the session reference to attach to subsequent reports. */
@@ -95,6 +122,11 @@ export class HerdrReporter {
     this.sessionId = id
   }
 
+  /** Record the session log path (jsonl backends) to attach to session reports. */
+  setSessionPath(path) {
+    this.sessionPath = typeof path === 'string' && path !== '' ? path : undefined
+  }
+
   nextSeq() {
     this.seq += 1
     return this.seq
@@ -102,7 +134,10 @@ export class HerdrReporter {
 
   sessionParams() {
     if (this.reportSessionRef && this.sessionId !== undefined && this.sessionId !== '') {
-      return { agent_session_id: this.sessionId }
+      return {
+        agent_session_id: this.sessionId,
+        ...(this.sessionPath !== undefined ? { agent_session_path: this.sessionPath } : {}),
+      }
     }
     return {}
   }
@@ -121,12 +156,69 @@ export class HerdrReporter {
     void this.drain()
   }
 
+  /**
+   * Report display-only Herdr pane metadata. Title and state labels are
+   * presentation fields and carry the `agent` / `applies_to_source` guards, so
+   * they display exactly while this reporter holds the pane's lifecycle
+   * authority; tokens always apply and are this reporter's to clear. One
+   * combined request carries whichever kinds changed; nothing is sent when
+   * nothing did.
+   *
+   * @param {{ title?: string, tokens?: Record<string, string | null>, state_labels?: Record<string, string> } | undefined} fields
+   */
+  reportMetadata(fields = {}) {
+    const params = { pane_id: this.paneId, source: this.source }
+    let guarded = false
+
+    if (
+      this.reportTitleRef &&
+      typeof fields.title === 'string' &&
+      fields.title.trim() !== '' &&
+      fields.title !== this.lastSentTitle
+    ) {
+      this.lastSentTitle = fields.title
+      params.title = fields.title
+      guarded = true
+    }
+    if (
+      fields.state_labels !== undefined &&
+      Object.keys(fields.state_labels).length > 0 &&
+      !shallowEqual(fields.state_labels, this.lastSentStateLabels)
+    ) {
+      this.lastSentStateLabels = { ...fields.state_labels }
+      params.state_labels = { ...fields.state_labels }
+      guarded = true
+    }
+    if (
+      this.reportTokensRef &&
+      fields.tokens !== undefined &&
+      Object.keys(fields.tokens).length > 0 &&
+      !shallowEqual(fields.tokens, this.lastSentTokens)
+    ) {
+      this.lastSentTokens = { ...fields.tokens }
+      params.tokens = { ...fields.tokens }
+      for (const key of Object.keys(fields.tokens)) this.sentTokenKeys.add(key)
+    }
+
+    if (params.title === undefined && params.state_labels === undefined && params.tokens === undefined) return
+    if (guarded) {
+      params.agent = this.agent
+      params.applies_to_source = this.source
+    }
+    params.seq = this.nextSeq()
+    void this.send({
+      id: requestId(`${this.source}:meta`),
+      method: 'pane.report_metadata',
+      params,
+    })
+  }
+
   /** 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)}`,
+      id: requestId(`${this.source}:session`),
       method: 'pane.report_agent_session',
       params: {
         pane_id: this.paneId,
@@ -139,10 +231,33 @@ export class HerdrReporter {
     })
   }
 
-  /** Release this pane's lifecycle authority (on unload or process exit). */
+  /**
+   * Release this pane's lifecycle authority (on unload or process exit). The
+   * guards on presentation metadata are checked when a report arrives, not
+   * continuously, so every metadata kind this reporter sent is cleared
+   * explicitly alongside the release.
+   */
   release() {
+    const clear = {}
+    if (this.reportTitleRef && this.lastSentTitle !== undefined) clear.clear_title = true
+    if (this.lastSentStateLabels !== undefined) clear.clear_state_labels = true
+    if (this.reportTokensRef && this.sentTokenKeys.size > 0) {
+      clear.tokens = {}
+      for (const key of this.sentTokenKeys) clear.tokens[key] = null
+    }
+    if (Object.keys(clear).length > 0) {
+      this.lastSentTitle = undefined
+      this.lastSentStateLabels = undefined
+      this.lastSentTokens = undefined
+      this.sentTokenKeys.clear()
+      void this.send({
+        id: requestId(`${this.source}:meta-clear`),
+        method: 'pane.report_metadata',
+        params: { pane_id: this.paneId, source: this.source, ...clear, seq: this.nextSeq() },
+      })
+    }
     void this.send({
-      id: `${this.source}:release:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+      id: requestId(`${this.source}:release`),
       method: 'pane.release_agent',
       params: { pane_id: this.paneId, source: this.source, agent: this.agent },
     })
@@ -157,7 +272,7 @@ export class HerdrReporter {
         this.queued = undefined
         const params = this.sessionParams()
         await this.send({
-          id: `${this.source}:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+          id: requestId(`${this.source}:state`),
           method: 'pane.report_agent',
           params: {
             pane_id: this.paneId,