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

package/README.md

@@ -1,12 +1,13 @@
 # @dsh-blue/herdr-agent-state
 
 A DeepSeek Harness (`dsh`) plugin that reports a pane's agent state — `working`,
-`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)
+`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
@@ -60,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
@@ -69,27 +77,38 @@ 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
+## 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
 
@@ -103,6 +122,9 @@ title through Herdr's display-only `pane.report_metadata` channel:
 | `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
@@ -134,6 +156,14 @@ the patch is skipped with a warning instead of silently applying:
     reportSession: true
     title: session
     message: tool
+    workingMessage: tool
+    tokens: auto
+    stateLabels:
+      idle: ''
+      working: ''
+      blocked: ''
+      done: ''
+      unknown: ''
     enabled: true
 ```
 
@@ -165,6 +195,26 @@ Disable title reporting (keep state and session reports):
     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
@@ -176,9 +226,10 @@ Disable title reporting (keep state and session reports):
 - **`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.
+- 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.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dsh-blue/herdr-agent-state",
-  "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.",
+  "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,12 +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), 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.
+ * 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`.
@@ -17,7 +18,7 @@
 
 import z from '@deepseek-ai/schemastery'
 
-import { AgentStateModel, SessionTitleModel } from './state.js'
+import { AgentStateModel, SessionFactsModel, stateLabelsPayload, sumUsageTokens } from './state.js'
 import { HerdrReporter, herdrEnabled } from './transport.js'
 
 export const name = 'herdr-agent-state'
@@ -53,6 +54,24 @@ export const Config = z.object({
   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),
 })
@@ -64,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, title: 'session' | 'none', 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
@@ -83,14 +126,18 @@ export function apply(ctx, config) {
     agent: config.agent,
     reportSession: config.reportSession,
     reportTitle: config.title !== 'none',
+    reportTokens: config.tokens !== 'none',
     env,
   })
   const model = new AgentStateModel()
-  const titleModel = new SessionTitleModel()
+  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)
@@ -108,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()
@@ -131,32 +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) => {
     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)
-    // A resumed session's past titles are constructor-seed log events that
-    // never reach the session/event feed, so read the current one directly.
+    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.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))
+    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,70 +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 title is current and the latest applicable title,
- * deciding when a title observation should be published.
+ * 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 SessionTitleModel {
+export class SessionFactsModel {
   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
+    /** 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 title (a resumed session's title predates the plugin),
-   * resetting change tracking so an identical title re-publishes.
+   * 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 {string | undefined} [initialTitle]
-   * @returns {string | undefined} the title to publish now, if any
+   * @param {{ title?: string, model?: string, contextWindow?: number, usedTokens?: number }} [initial]
+   * @returns {{ title?: string, tokens?: Record<string, string | null> } | undefined}
    */
-  setSession(sessionId, initialTitle) {
+  setSession(sessionId, initial = {}) {
     this.sessionId = sessionId
-    this.title = initialTitle
-    this.lastReported = undefined
+    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()
   }
 
   /**
-   * 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).
+   * 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 {string} title
-   * @returns {string | undefined} the title to publish now, if changed
+   * @param {{ type: string, data?: unknown }} event
+   * @returns {{ title?: string, tokens?: Record<string, string | null> } | undefined}
    */
-  observeTitle(sessionId, title) {
+  observeEvent(sessionId, event) {
     if (this.sessionId === undefined) this.sessionId = sessionId
     if (sessionId === undefined || sessionId !== this.sessionId) return undefined
-    this.title = title
+    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 report derived from the current inputs.
-   * @returns {{ title: string } | undefined}
-   */
-  desired() {
-    return typeof this.title === 'string' && this.title.trim() !== ''
-      ? { title: this.title }
-      : undefined
+  /** The publishable title, when it is a non-blank string. */
+  desiredTitle() {
+    return typeof this.title === 'string' && this.title.trim() !== '' ? this.title : undefined
   }
 
-  /** Consume the desired report once, tracking it as reported. */
+  /** 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 report = this.desired()
-    if (report === undefined || report.title === this.lastReported) return undefined
-    this.lastReported = report.title
-    return report.title
+    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,10 +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 — 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).
+ * `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
@@ -25,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
@@ -72,25 +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, reportTitle?: 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. */
@@ -98,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
@@ -105,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 {}
   }
@@ -124,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,
@@ -142,53 +231,33 @@ export class HerdrReporter {
     })
   }
 
-  /**
-   * 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.
+   * 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() {
-    if (this.reportTitleRef && this.lastSentTitle !== undefined) {
+    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: `${this.source}:title-clear:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+        id: requestId(`${this.source}:meta-clear`),
         method: 'pane.report_metadata',
-        params: {
-          pane_id: this.paneId,
-          source: this.source,
-          clear_title: true,
-          seq: this.nextSeq(),
-        },
+        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 },
     })
@@ -203,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,