@dorokuma/herdsman 0.13.6 → 0.14.0

package/README.md

@@ -6,7 +6,7 @@ Herdsman is a daemon-backed observability layer for coding agents running in Her
 
 Herdr's `herdr agent read` reads terminal streams or scrollback. Herdsman instead reads agent session data so callers can retrieve work status, structured message excerpts, compact tool results, and unread outcomes without parsing terminal output. Herdsman is read-only; use the official Herdr CLI or skill for agent start, prompts, waits, pane operations, and terminal control.
 
-Herdsman currently supports session history from Claude Code, Codex, Gemini CLI, OpenCode, Pi, Grok, and Antigravity CLI.
+Herdsman resolves each pane's session history from the session identifier Herdr reports for that pane, never by scanning agent directories. It supports exactly two agents, both through values Herdr itself reports. Pi panes normally get a session path straight from Herdr, and Herdsman reads that file; when the pi integration cannot read its own session file path it sends an id instead, which Herdsman does not resolve — a pi session file name cannot be derived from its id alone — so such a pane reports no history. Antigravity CLI (`agy`) panes report a conversation id, and because that id names the conversation's own database file, Herdsman resolves it to `<home>/.gemini/antigravity-cli/conversations/<id>.db`, and only for a single exact match. Every other agent reports no history, whether or not Herdr has an integration for it (`herdr integration install <agent>`): Herdsman deliberately does not resolve any other agent's session identifier and never reads any other agent's session store. When the official value cannot be resolved — the agent has no installed integration, an id has no derivation Herdsman can verify, or the file is missing or fails Herdsman's file-safety checks — Herdsman logs one warning and reports the pane without history rather than guessing.
 
 ## Development conventions
 
@@ -130,7 +130,7 @@ Set `filter_upstream_errors: false` to restore waking on every outcome. `HERDSMA
 Install the optional plugin from the GitHub release tag:
 
 ```bash
-herdr plugin install dorokuma/herdsman/packages/herdsman-herdr-plugin --ref v0.13.6 --yes
+herdr plugin install dorokuma/herdsman/packages/herdsman-herdr-plugin --ref v0.14.0 --yes
 ```
 
 Use the release tag that matches the installed Herdsman CLI version.

package/dist/src/agent-history/discovery.d.ts

@@ -1,23 +1,59 @@
 import type { AgentHistoryRef, AgentSessionRef } from "../observability/contracts.js";
+/**
+ * Herdsman supports session history for exactly two agents, by decision:
+ *
+ * 1. `pi` — Herdr's own integration reports the session file itself, so the
+ *    official `agent_session.kind == "path"` value is used as-is after the
+ *    file-safety gate (this is the generic path channel, not a pi-only branch).
+ * 2. `agy` — Herdr reports only `kind == "id"`, and an agy conversation id is
+ *    the name of its own conversation database, so the id resolves to exactly
+ *    one candidate:
+ *      - `agy` -> `<home>/.gemini/antigravity-cli/conversations/<id>.db`
+ *
+ * Every other agent — whether or not Herdr has an integration for it — is
+ * deliberately not resolved: herdsman does not walk agent directories, rank
+ * candidates by mtime/cwd, match role directories from the terminal title, or
+ * pick "the newest plausible file". An unresolvable pane is an explicit failure:
+ * one `console.warn` naming the official values plus the derived candidate path,
+ * then `null`.
+ */
 export declare const ALLOWED_SESSION_ROOTS: readonly ["/tmp/herdr-role-sessions"];
-export declare const DISCOVERY_RECENCY_GRACE_MS = 30000;
-export declare const FALLBACK_DISCOVERY_RECENCY_GRACE_MS: number;
 export type AgentHistoryLookupInput = {
     agent: string | null;
     agentSession: AgentSessionRef | null;
-    cwd: string | null;
-    foregroundCwd: string | null;
-    firstSeenAtMs?: number;
-    grokHome?: string;
     herdrSessionName?: string;
     homeDir?: string;
-    occupiedSessionPaths?: ReadonlySet<string>;
-    terminalTitle?: string | null;
+    paneId?: string | null;
 };
-export declare function discoverAgentHistory(input: AgentHistoryLookupInput): Promise<AgentHistoryRef | null>;
+export declare function discoveryLookupKey(input: AgentHistoryLookupInput): string;
+/**
+ * True while the very same official values are still inside their retry window,
+ * so callers can skip the lookup the pane would otherwise repeat every round.
+ */
+export declare function discoveryFailureFresh(input: AgentHistoryLookupInput, now?: number): boolean;
+export declare function discoverAgentHistory(input: AgentHistoryLookupInput, options?: {
+    force?: boolean;
+}): Promise<AgentHistoryRef | null>;
+/**
+ * Maps an official `agent_session` to the reader that can read it. Only the two
+ * supported agents have a reader; everything else is `unknown`, which every
+ * reader rejects. `source` looks like `herdr:<agent>`, so segments are matched
+ * whole — `herdr:copilot` contains "pi" and must never be read as a pi session.
+ */
 export declare function historySourceFromSessionRef(ref: AgentSessionRef): AgentHistoryRef["source"];
 export declare function safeAllowedSessionPath(value: string, homeDir?: string): string | null;
-export declare function usesShortDiscoveryRecency(input: Pick<AgentHistoryLookupInput, "agent" | "agentSession" | "terminalTitle">): boolean;
-export declare function discoveryRecencyGraceMs(input: Pick<AgentHistoryLookupInput, "agent" | "agentSession" | "terminalTitle">): number;
+/**
+ * File-safety gate for an official session path reported by Herdr.
+ *
+ * Herdr only reports back the value an installed agent integration handed it
+ * (`pane.report_agent_session`), so the *root* of an official path is not
+ * guessed any more and is deliberately not whitelisted: pi keeps its sessions
+ * under its own agent home, and a fixed root list would silently reject those
+ * official values. What is still enforced is that herdsman only reads a regular,
+ * non-symlink file it owns and that no other principal can rewrite behind it.
+ * `safeAllowedSessionPath` keeps the root whitelist for the herdsman-pi
+ * registration protocol, where a pane claims a path itself.
+ */
+export declare function safeOfficialSessionPath(value: string): string | null;
 export declare function sessionPathAllowedByShape(value: string, homeDir?: string): boolean;
 //# sourceMappingURL=discovery.d.ts.map

package/dist/src/agent-history/discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/agent-history/discovery.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAerF,eAAO,MAAM,qBAAqB,uCAAwC,CAAC;AAE3E,eAAO,MAAM,0BAA0B,QAAS,CAAC;AACjD,eAAO,MAAM,mCAAmC,QAAc,CAAC;AAC/D,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,EAAE,eAAe,GAAG,IAAI,CAAC;IACrC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oBAAoB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3C,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAAC;AASF,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CA8GjC;AAED,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,eAAe,GAAG,eAAe,CAAC,QAAQ,CAAC,CAiB3F;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwBrF;AAkBD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,IAAI,CAAC,uBAAuB,EAAE,OAAO,GAAG,cAAc,GAAG,eAAe,CAAC,GAC/E,OAAO,CAGT;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,IAAI,CAAC,uBAAuB,EAAE,OAAO,GAAG,cAAc,GAAG,eAAe,CAAC,GAC/E,MAAM,CAIR;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CASlF"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/agent-history/discovery.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAErF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,uCAAwC,CAAC;AAE3E,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,EAAE,eAAe,GAAG,IAAI,CAAC;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAuBF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,CAQzE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,uBAAuB,EAAE,GAAG,SAAa,GAAG,OAAO,CAG/F;AAsBD,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,uBAAuB,EAC9B,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAoCjC;AAyGD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,eAAe,GAAG,eAAe,CAAC,QAAQ,CAAC,CAO3F;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWrF;AAkCD;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEpE;AAID,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CASlF"}