A self-improving RLM agent for coding workflows and long-running autonomous tasks.
Rust
add built-in herdr integration (#360)
ktecd32905eeed
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.mdindex 2087e7ffe4..02c7214d53 100644--- a/packages/coding-agent/CHANGELOG.md+++ b/packages/coding-agent/CHANGELOG.md@@ -2,6 +2,7 @@## [Unreleased]+- Added built-in Herdr integration that reports agent lifecycle state to Herdr panes automatically, without requiring `herdr integration install pi`.- Changed Escape to interrupt active work with a visible abort notice, double Escape to open the session tree from an empty prompt or clear an idle draft, and `?` to show shortcuts ([ENG-4489](https://linear.app/primeintellect/issue/ENG-4489/rewire-prime-agent-shortcuts-to-match-claude-code-flow)).- Changed new-chat guidance to show concise shell, command, file, and shortcut hints, with Agents View first and `? for shortcuts` after the model and effort ([ENG-4489](https://linear.app/primeintellect/issue/ENG-4489/rewire-prime-agent-shortcuts-to-match-claude-code-flow)).- Changed `?` shortcut help to appear as a temporary compact panel below the transcript, while `/hotkeys` shows the full reference without Ctrl+Z ([ENG-4489](https://linear.app/primeintellect/issue/ENG-4489/rewire-prime-agent-shortcuts-to-match-claude-code-flow)).diff --git a/packages/coding-agent/src/core/agent-session-services.ts b/packages/coding-agent/src/core/agent-session-services.tsindex ae053107ec..fc0d28b443 100644--- a/packages/coding-agent/src/core/agent-session-services.ts+++ b/packages/coding-agent/src/core/agent-session-services.ts@@ -7,6 +7,7 @@ import type { AgentObserveController } from "./agent-observe.js";import { installAgentTraceUpload } from "./agent-traces.js";import { AuthStorage } from "./auth-storage.js";import type { AgentRlmHeartbeatController } from "./cron-jobs.js";+import { createHerdrAgentStateExtension } from "./extensions/builtin/herdr-agent-state.js";import type { SessionStartEvent, ToolDefinition } from "./extensions/index.js";import { McpManager } from "./mcp/mcp-manager.js";import { ModelRegistry } from "./model-registry.js";@@ -43,6 +44,13 @@ export interface CreateAgentSessionServicesOptions {modelRegistry?: ModelRegistry;extensionFlagValues?: Map<string, boolean | string>;resourceLoaderOptions?: Omit<DefaultResourceLoaderOptions, "cwd" | "agentDir" | "settingsManager">;+ /**+ * Skip the built-in Herdr reporter for these services. Set for RLM subagent+ * runtimes: they inherit the parent's HERDR_* pane identity, so their own+ * reporter would race the parent's on the same pane and a subagent quit+ * would release the pane while the parent is still running.+ */+ noBuiltinHerdrReporter?: boolean;}export interface AgentSessionCreationOptions {@@ -167,8 +175,21 @@ export async function createAgentSessionServices(// refresh() resets the OAuth registry to built-ins; re-add user MCP providers too.modelRegistry.setOnOAuthProvidersReset(() => mcpManager.registerUserProviders());- const resourceLoader = new DefaultResourceLoader({+ const userExtensionFactories = options.resourceLoaderOptions?.extensionFactories ?? [];+ // The built-in Herdr reporter defers to Herdr's own file-based integration+ // when the loader actually loaded it; two reporters would race on the same+ // pane. Deferral is late-bound to the loader's loaded paths (inline+ // factories run after file extensions load), so a file that exists but is+ // disabled or never discovered does not silence the built-in.+ // noExtensions is a full opt-out: it disables the built-in reporter too,+ // not just discovered extension files.+ const skipHerdrReporter = options.noBuiltinHerdrReporter || options.resourceLoaderOptions?.noExtensions;+ const builtinExtensionFactories = skipHerdrReporter+ ? []+ : [createHerdrAgentStateExtension(() => resourceLoader.getLoadedExtensionPaths())];+ const resourceLoader: DefaultResourceLoader = new DefaultResourceLoader({...(options.resourceLoaderOptions ?? {}),+ extensionFactories: [...builtinExtensionFactories, ...userExtensionFactories],cwd,agentDir,settingsManager,diff --git a/packages/coding-agent/src/core/extensions/builtin/herdr-agent-state.ts b/packages/coding-agent/src/core/extensions/builtin/herdr-agent-state.tsnew file mode 100644index 0000000000..38b6e1efd2--- /dev/null+++ b/packages/coding-agent/src/core/extensions/builtin/herdr-agent-state.ts@@ -0,0 +1,461 @@+/**+ * Built-in Herdr integration extension.+ *+ * Reports agent lifecycle state (working/idle/blocked) to the Herdr terminal+ * workspace manager via its Unix socket. This is the in-tree equivalent of+ * the extension that `herdr integration install pi` writes, so Prime Agent+ * works inside Herdr panes out of the box without a manual install step.+ *+ * Unlike the file-based integration (re-evaluated per session load by jiti),+ * this module is statically imported and evaluated once per process. All env+ * capture and state therefore live inside the factory, which the resource+ * loader invokes per session load — inside the daemon's client-env window —+ * so each daemon session captures its own pane identity.+ *+ * The factory is a complete no-op when `HERDR_ENV` is not `"1"` (i.e. when+ * not running inside a Herdr pane), so it is safe to always load.+ */++import { createConnection } from "node:net";+import { basename } from "node:path";+import type { ExtensionAPI, ExtensionFactory } from "../types.js";++type AgentState = "working" | "blocked" | "idle";++/**+ * True when Herdr's own file-based Pi integration (`herdr integration+ * install pi`) is among the extension files the loader actually loaded this+ * cycle. That extension reports with the same `herdr:pi` source but its own+ * seq counter, so running the built-in alongside it would make the two+ * reporters race on one pane.+ *+ * Loaded paths — not raw disk existence — are the deferral source of truth:+ * a file that exists but never loads (settings `!` overrides, noExtensions,+ * paths outside the discovery dirs such as the legacy `~/.pi/agent/`) never+ * becomes an active reporter, and deferring to it would leave the pane with+ * no reporter at all.+ */+export function hasFileBasedHerdrIntegration(loadedExtensionPaths: string[]): boolean {+ return loadedExtensionPaths.some((path) => {+ const base = basename(path);+ return base === "herdr-agent-state.ts" || base === "herdr-agent-state.js";+ });+}++interface QueuedState {+ state: AgentState;+ message?: string;+ seq: number;+}++function parseDurationEnv(name: string, fallback: number): number {+ const raw = process.env[name];+ if (!raw) {+ return fallback;+ }+ const parsed = Number.parseInt(raw, 10);+ if (!Number.isFinite(parsed) || parsed < 0) {+ return fallback;+ }+ return parsed;+}++function lastAssistantMessage(messages: unknown[]): any | undefined {+ for (let i = messages.length - 1; i >= 0; i -= 1) {+ const message = messages[i] as any;+ if (message?.role === "assistant") {+ return message;+ }+ }+ return undefined;+}++/**+ * Error message of the turn's final assistant message, if it ended in error.+ *+ * The agent's auto-retry treats nearly every provider error as retryable and+ * kicks in after extension agent_end fires, so any error end may be followed+ * by a retry. Rather than second-guessing the agent's classification with a+ * pattern list, hold "working" for every error through the retry grace+ * window: if a retry starts, agent_start keeps the pane working; if none+ * does, the hold settles to blocked with the error message.+ */+function errorHoldMessage(event: any): string | undefined {+ const messages = Array.isArray(event?.messages) ? event.messages : [];+ const assistant = lastAssistantMessage(messages);+ if (assistant?.stopReason !== "error") {+ return undefined;+ }+ return String(assistant.errorMessage ?? "") || "provider error";+}++// Monotonic across all extension instances in this process. Herdr guards+// pane.report_agent with a per-source seq and silently drops lower-seq+// reports, so a successor session instance (after /new, resume, fork, or+// reload) must never restart below a seq the previous instance already used —+// otherwise its idle reports are dropped and the pane sticks at "working".+let reportSeq = Date.now() * 1000;++function nextReportSeq(): number {+ reportSeq = Math.max(reportSeq + 1, Date.now() * 1000);+ return reportSeq;+}++/**+ * Build the built-in Herdr reporter factory. `getLoadedExtensionPaths`+ * returns the extension files the resource loader actually loaded in the+ * current cycle; it is re-checked on every factory invocation (i.e. on every+ * session load and `/reload`), so installing Herdr's own file-based+ * integration and reloading hands the pane over to it without also keeping+ * the built-in active — while a file that exists but never loads (settings+ * overrides, legacy paths) does not silence the built-in.+ */+export function createHerdrAgentStateExtension(getLoadedExtensionPaths: () => string[]): ExtensionFactory {+ return (pi: ExtensionAPI) => {+ herdrAgentStateExtensionImpl(pi, getLoadedExtensionPaths);+ };+}++/** Built-in reporter with no file-based deferral, for tests and embedders. */+export const herdrAgentStateExtension: ExtensionFactory = (pi: ExtensionAPI) => {+ herdrAgentStateExtensionImpl(pi, () => []);+};++function herdrAgentStateExtensionImpl(pi: ExtensionAPI, getLoadedExtensionPaths: () => string[]): void {+ // Captured per factory invocation: the resource loader runs this during+ // session load, inside the daemon's client-env window, so these reflect the+ // session's own Herdr pane rather than the daemon's startup environment.+ const socketPath = process.env.HERDR_SOCKET_PATH;+ const paneId = process.env.HERDR_PANE_ID;+ const enabled = process.env.HERDR_ENV === "1" && !!socketPath && !!paneId;+ if (!enabled || hasFileBasedHerdrIntegration(getLoadedExtensionPaths())) {+ return;+ }++ const source = "herdr:pi";+ const agentLabel = "prime-agent";+ const idleDebounceMs = parseDurationEnv("HERDR_PI_IDLE_DEBOUNCE_MS", 250);+ const retryGraceMs = parseDurationEnv("HERDR_PI_RETRY_GRACE_MS", 2500);++ let currentAgentSessionId: string | undefined;+ let currentAgentSessionPath: string | undefined;+ // Inline RLM child sessions reuse the parent's resource loader, so their+ // extension runners re-bind these same handler closures. Bind the reporter+ // to the first session that starts (the parent) and ignore events other+ // sessions deliver, or a subagent's turns would flip the pane state and+ // stomp the parent's session reference.+ let boundSessionManager: unknown;+ let sendInFlight = false;+ let queuedState: QueuedState | undefined;+ let activeDrain: Promise<void> = Promise.resolve();+ let released = false;++ let agentActive = false;+ let retryHoldActive = false;+ let failureBlocked = false;+ let failureMessage: string | undefined;+ let blockedCount = 0;+ let blockedMessage: string | undefined;+ let lastState: AgentState | undefined;+ let lastMessage: string | undefined;+ let idleTimer: ReturnType<typeof setTimeout> | undefined;+ let retryTimer: ReturnType<typeof setTimeout> | undefined;++ function sendRequest(request: unknown): Promise<void> {+ return new Promise((resolve) => {+ let done = false;+ const finish = () => {+ if (done) return;+ done = true;+ socket.destroy();+ resolve();+ };++ const socket = createConnection(socketPath!);+ socket.on("error", finish);+ socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));+ socket.on("data", finish);+ socket.on("end", finish);+ const timeout = setTimeout(finish, 500);+ timeout.unref?.();+ });+ }++ function isBoundSession(ctx: any): boolean {+ if (boundSessionManager === undefined) {+ return true;+ }+ return ctx?.sessionManager === boundSessionManager;+ }++ function updateSessionRef(ctx: any): void {+ try {+ const file = ctx?.sessionManager?.getSessionFile?.();+ currentAgentSessionPath = typeof file === "string" && file.startsWith("/") ? file : undefined;+ } catch {+ currentAgentSessionPath = undefined;+ }++ try {+ const id = ctx?.sessionManager?.getSessionId?.();+ currentAgentSessionId = typeof id === "string" && id.length > 0 ? id : undefined;+ } catch {+ currentAgentSessionId = undefined;+ }+ }++ function withSessionRef(params: Record<string, unknown>): Record<string, unknown> {+ if (currentAgentSessionPath) {+ return { ...params, agent_session_path: currentAgentSessionPath };+ }+ if (currentAgentSessionId) {+ return { ...params, agent_session_id: currentAgentSessionId };+ }+ return params;+ }++ function sendState(state: AgentState, message?: string, seq = nextReportSeq()): Promise<void> {+ return sendRequest({+ id: `${source}:${Date.now()}:${Math.random().toString(36).slice(2)}`,+ method: "pane.report_agent",+ params: withSessionRef({+ pane_id: paneId,+ source,+ agent: agentLabel,+ state,+ message,+ seq,+ }),+ });+ }++ function queueState(state: AgentState, message?: string): void {+ if (released) {+ // The pane was released on quit; a late report would reclaim it and+ // leave Herdr showing an agent that already exited.+ return;+ }+ queuedState = { state, message, seq: nextReportSeq() };+ if (!sendInFlight) {+ activeDrain = drainStateQueue();+ }+ }++ async function drainStateQueue(): Promise<void> {+ if (sendInFlight) {+ return;+ }++ sendInFlight = true;+ try {+ while (queuedState) {+ const next = queuedState;+ queuedState = undefined;+ await sendState(next.state, next.message, next.seq);+ }+ } finally {+ sendInFlight = false;+ if (queuedState) {+ activeDrain = drainStateQueue();+ }+ }+ }++ async function releaseAgent(): Promise<void> {+ // Stop new reports, drop anything still queued, and wait for the+ // in-flight send to finish so the release is the last write on the wire;+ // a report landing after the release would reclaim the pane.+ released = true;+ queuedState = undefined;+ await activeDrain.catch(() => undefined);+ return sendRequest({+ id: `${source}:release:${Date.now()}:${Math.random().toString(36).slice(2)}`,+ method: "pane.release_agent",+ params: {+ pane_id: paneId,+ source,+ agent: agentLabel,+ seq: nextReportSeq(),+ },+ });+ }++ function clearTimer(timer: ReturnType<typeof setTimeout> | undefined) {+ if (timer) {+ clearTimeout(timer);+ }+ }++ function clearPendingTimers() {+ clearTimer(idleTimer);+ clearTimer(retryTimer);+ idleTimer = undefined;+ retryTimer = undefined;+ }++ function clearFailureState() {+ retryHoldActive = false;+ failureBlocked = false;+ failureMessage = undefined;+ }++ function desiredState(): { state: AgentState; message?: string } {+ if (blockedCount > 0) {+ return { state: "blocked", message: blockedMessage };+ }+ if (failureBlocked) {+ return { state: "blocked", message: failureMessage };+ }+ if (agentActive || retryHoldActive) {+ return { state: "working", message: undefined };+ }+ return { state: "idle", message: undefined };+ }++ function publishState(force = false) {+ const next = desiredState();+ if (!force && next.state === lastState && next.message === lastMessage) {+ return;+ }+ lastState = next.state;+ lastMessage = next.message;+ queueState(next.state, next.message);+ }++ function scheduleIdle() {+ clearPendingTimers();+ clearFailureState();+ idleTimer = setTimeout(() => {+ idleTimer = undefined;+ publishState();+ }, idleDebounceMs);+ idleTimer.unref?.();+ }++ function holdForRetry(message: string) {+ clearPendingTimers();+ retryHoldActive = true;+ failureBlocked = false;+ failureMessage = message;+ publishState();++ retryTimer = setTimeout(() => {+ retryTimer = undefined;+ retryHoldActive = false;+ failureBlocked = true;+ publishState();+ }, retryGraceMs);+ retryTimer.unref?.();+ }++ pi.on("session_start", (_event, ctx) => {+ if (!isBoundSession(ctx)) {+ return;+ }+ if (boundSessionManager === undefined && ctx?.sessionManager !== undefined) {+ boundSessionManager = ctx.sessionManager;+ }+ updateSessionRef(ctx);+ // A reload can re-create this reporter mid-turn (daemon-driven reloads+ // and extension ctx.reload() are not gated on idle). Seed the active+ // flag from the session so the fresh instance does not report idle+ // while the agent is still streaming, which would also make the guard+ // in agent_end swallow the turn's real end transition.+ if (typeof ctx?.isIdle === "function") {+ try {+ agentActive = !ctx.isIdle();+ } catch {+ agentActive = false;+ }+ }+ publishState(true);+ });++ const unsubscribeBlocked = pi.events.on("herdr:blocked", (data: any) => {+ if (!data?.active) {+ blockedCount = Math.max(0, blockedCount - 1);+ if (blockedCount === 0) {+ blockedMessage = undefined;+ }+ publishState();+ return;+ }++ clearPendingTimers();+ // clearPendingTimers cancelled the retry timer; settle the hold the way+ // the timer would have, or retryHoldActive keeps desiredState() at+ // "working" forever once the block lifts.+ if (retryHoldActive) {+ retryHoldActive = false;+ failureBlocked = true;+ }+ blockedCount += 1;+ blockedMessage = data.label;+ publishState();+ });++ pi.on("agent_start", (_event, ctx) => {+ if (!isBoundSession(ctx)) {+ return;+ }+ clearPendingTimers();+ clearFailureState();+ agentActive = true;+ publishState();+ });++ pi.on("agent_end", (event, ctx) => {+ if (!isBoundSession(ctx)) {+ return;+ }+ if (!agentActive) {+ // Duplicate/late end events can arrive while auto-retry is already+ // holding the pane in Working. Do not let an unqualified duplicate end+ // cancel the retry hold and publish a false Idle.+ return;+ }++ agentActive = false;++ const holdMessage = errorHoldMessage(event);+ if (holdMessage) {+ holdForRetry(holdMessage);+ return;+ }++ // Queued follow-up/steer messages start another loop right away; debounce+ // so the pane does not flicker done -> working. With nothing queued,+ // report idle immediately so Herdr flips to done as streaming finishes.+ if (typeof ctx?.hasPendingMessages === "function" && ctx.hasPendingMessages()) {+ scheduleIdle();+ return;+ }++ clearPendingTimers();+ clearFailureState();+ publishState();+ });++ pi.on("session_shutdown", async (event, ctx) => {+ if (!isBoundSession(ctx)) {+ return;+ }+ clearPendingTimers();+ // The event bus is shared across reloads and session replacements, so a+ // listener left behind would keep this stale instance reporting with a+ // captured (possibly wrong) pane identity forever.+ unsubscribeBlocked();+ // On session replacement (new/resume/fork) or reload, a successor+ // instance in this same pane re-reports immediately. Releasing here+ // races that report: two independent socket writes with no ordering,+ // and a release that lands after the successor's report clears the+ // pane. Only a real quit should release; every shutdown silences this+ // instance so no stale queued report lands around the successor's.+ if (event?.reason !== "quit") {+ released = true;+ queuedState = undefined;+ return;+ }+ await releaseAgent();+ });+}diff --git a/packages/coding-agent/src/core/extensions/index.ts b/packages/coding-agent/src/core/extensions/index.tsindex 0a508b4039..820b6b47d9 100644--- a/packages/coding-agent/src/core/extensions/index.ts+++ b/packages/coding-agent/src/core/extensions/index.ts@@ -4,6 +4,12 @@export type { SlashCommandInfo, SlashCommandSource } from "../slash-commands.js";export type { SourceInfo } from "../source-info.js";+// Built-in extensions+export {+ createHerdrAgentStateExtension,+ hasFileBasedHerdrIntegration,+ herdrAgentStateExtension,+} from "./builtin/herdr-agent-state.js";export {createExtensionRuntime,discoverAndLoadExtensions,diff --git a/packages/coding-agent/src/core/resource-loader.ts b/packages/coding-agent/src/core/resource-loader.tsindex b5f019b199..5cb03a4bf5 100644--- a/packages/coding-agent/src/core/resource-loader.ts+++ b/packages/coding-agent/src/core/resource-loader.ts@@ -193,6 +193,7 @@ export class DefaultResourceLoader implements ResourceLoader {private appendSystemPromptOverride?: (base: string[]) => string[];private extensionsResult: LoadExtensionsResult;+ private loadedExtensionPaths: string[] = [];private skills: Skill[];private skillDiagnostics: ResourceDiagnostic[];private prompts: PromptTemplate[];@@ -263,6 +264,11 @@ export class DefaultResourceLoader implements ResourceLoader {return this.extensionsResult;}+ /** Extension file paths the last reload actually loaded (after settings overrides). */+ getLoadedExtensionPaths(): string[] {+ return this.loadedExtensionPaths;+ }+getSkills(): { skills: Skill[]; diagnostics: ResourceDiagnostic[] } {return { skills: this.skills, diagnostics: this.skillDiagnostics };}@@ -405,6 +411,10 @@ export class DefaultResourceLoader implements ResourceLoader {: this.mergePaths(cliEnabledExtensions, enabledExtensions);const extensionsResult = await loadExtensions(extensionPaths, this.cwd, this.eventBus);+ // Set before inline factories run so a factory can see which file-based+ // extensions actually loaded this cycle (e.g. the built-in Herdr reporter+ // defers to Herdr's own file-based integration only when it is active).+ this.loadedExtensionPaths = extensionPaths;const inlineExtensions = await this.loadExtensionFactories(extensionsResult.runtime);extensionsResult.extensions.push(...inlineExtensions.extensions);extensionsResult.errors.push(...inlineExtensions.errors);diff --git a/packages/coding-agent/src/main.ts b/packages/coding-agent/src/main.tsindex 0783701aa4..cfbb715f06 100644--- a/packages/coding-agent/src/main.ts+++ b/packages/coding-agent/src/main.ts@@ -733,6 +733,9 @@ async function prepareRuntimeServices(options: {agentDir: effectiveAgentDir,authStorage,extensionFlagValues: new Map(Object.entries(config.extensionFlagValues ?? {})),+ // Subagents share the parent's Herdr pane; their own reporter would race+ // the parent's and a subagent quit would release the still-active pane.+ noBuiltinHerdrReporter: (options.sessionOptionsOverride?.rlmDepth ?? 0) > 0,resourceLoaderOptions: {additionalExtensionPaths: config.extensions,additionalSkillPaths: config.skills,diff --git a/packages/coding-agent/test/herdr-agent-state.test.ts b/packages/coding-agent/test/herdr-agent-state.test.tsnew file mode 100644index 0000000000..41a2423cbd--- /dev/null+++ b/packages/coding-agent/test/herdr-agent-state.test.ts@@ -0,0 +1,513 @@+import { mkdirSync, rmSync } from "node:fs";+import { createServer, type Server } from "node:net";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { afterEach, describe, expect, it } from "vitest";+import {+ createHerdrAgentStateExtension,+ hasFileBasedHerdrIntegration,+ herdrAgentStateExtension,+} from "../src/core/extensions/builtin/herdr-agent-state.js";+import type { ExtensionAPI } from "../src/core/extensions/types.js";++interface RecordedRequest {+ method: string;+ params: Record<string, unknown>;+}++function createMockPi() {+ const handlers = new Map<string, Array<(...args: unknown[]) => unknown>>();+ const busHandlers = new Map<string, Array<(...args: unknown[]) => unknown>>();+ const pi = {+ on(event: string, handler: (...args: unknown[]) => unknown) {+ const list = handlers.get(event) ?? [];+ list.push(handler);+ handlers.set(event, list);+ },+ events: {+ on(event: string, handler: (...args: unknown[]) => unknown) {+ const list = busHandlers.get(event) ?? [];+ list.push(handler);+ busHandlers.set(event, list);+ return () => {+ const current = busHandlers.get(event) ?? [];+ const index = current.indexOf(handler);+ if (index !== -1) {+ current.splice(index, 1);+ }+ };+ },+ },+ } as unknown as ExtensionAPI;+ return { pi, handlers, busHandlers };+}++async function startFakeHerdrServer(socketPath: string): Promise<{+ server: Server;+ requests: RecordedRequest[];+ waitForRequests: (count: number, timeoutMs?: number) => Promise<void>;+}> {+ const requests: RecordedRequest[] = [];+ const waiters: Array<{ count: number; resolve: () => void }> = [];++ const server = createServer((socket) => {+ let buffer = "";+ socket.on("data", (chunk) => {+ buffer += chunk.toString();+ let newlineIndex = buffer.indexOf("\n");+ while (newlineIndex >= 0) {+ const line = buffer.slice(0, newlineIndex);+ buffer = buffer.slice(newlineIndex + 1);+ if (line.trim()) {+ const parsed = JSON.parse(line);+ requests.push({ method: parsed.method, params: parsed.params });+ socket.write(`${JSON.stringify({ id: parsed.id, result: { type: "ok" } })}\n`);+ for (const waiter of [...waiters]) {+ if (requests.length >= waiter.count) {+ waiters.splice(waiters.indexOf(waiter), 1);+ waiter.resolve();+ }+ }+ }+ newlineIndex = buffer.indexOf("\n");+ }+ });+ });++ await new Promise<void>((resolve, reject) => {+ server.on("error", reject);+ server.listen(socketPath, resolve);+ });++ const waitForRequests = (count: number, timeoutMs = 3000): Promise<void> => {+ if (requests.length >= count) {+ return Promise.resolve();+ }+ return new Promise((resolve, reject) => {+ const timer = setTimeout(() => reject(new Error(`timed out waiting for ${count} herdr requests`)), timeoutMs);+ waiters.push({+ count,+ resolve: () => {+ clearTimeout(timer);+ resolve();+ },+ });+ });+ };++ return { server, requests, waitForRequests };+}++describe("herdrAgentStateExtension", () => {+ const cleanupPaths: string[] = [];+ const cleanupServers: Server[] = [];+ const savedEnv: Record<string, string | undefined> = {};+ const envKeys = [+ "HERDR_ENV",+ "HERDR_SOCKET_PATH",+ "HERDR_PANE_ID",+ "HERDR_PI_IDLE_DEBOUNCE_MS",+ "HERDR_PI_RETRY_GRACE_MS",+ "PRIME_AGENT_CODING_AGENT_DIR",+ ];++ for (const key of envKeys) {+ savedEnv[key] = process.env[key];+ }++ afterEach(async () => {+ for (const key of envKeys) {+ if (savedEnv[key] === undefined) {+ delete process.env[key];+ } else {+ process.env[key] = savedEnv[key];+ }+ }+ while (cleanupServers.length > 0) {+ const server = cleanupServers.pop();+ await new Promise<void>((resolve) => server?.close(() => resolve()));+ }+ while (cleanupPaths.length > 0) {+ const path = cleanupPaths.pop();+ if (path) {+ rmSync(path, { recursive: true, force: true });+ }+ }+ });++ it("registers no handlers when HERDR_ENV is not set", () => {+ delete process.env.HERDR_ENV;+ delete process.env.HERDR_SOCKET_PATH;+ delete process.env.HERDR_PANE_ID;++ const { pi, handlers, busHandlers } = createMockPi();+ herdrAgentStateExtension(pi);++ expect(handlers.size).toBe(0);+ expect(busHandlers.size).toBe(0);+ });++ it("detects the file-based herdr integration among loaded extension paths", () => {+ expect(hasFileBasedHerdrIntegration(["/x/extensions/herdr-agent-state.ts"])).toBe(true);+ expect(hasFileBasedHerdrIntegration(["/x/extensions/herdr-agent-state.js"])).toBe(true);+ expect(hasFileBasedHerdrIntegration(["/x/extensions/other.ts"])).toBe(false);+ expect(hasFileBasedHerdrIntegration([])).toBe(false);+ });++ it("defers only to a file-based integration that actually loaded", () => {+ const tempDir = join(tmpdir(), `pi-herdr-defer-${Date.now()}-${Math.random().toString(36).slice(2)}`);+ mkdirSync(tempDir, { recursive: true });+ cleanupPaths.push(tempDir);++ process.env.HERDR_ENV = "1";+ process.env.HERDR_SOCKET_PATH = join(tempDir, "h.sock");+ process.env.HERDR_PANE_ID = "w1:p1";++ // The loader reports the file-based integration as loaded: defer.+ let loadedPaths = [join(tempDir, "extensions", "herdr-agent-state.ts")];+ const factory = createHerdrAgentStateExtension(() => loadedPaths);+ const { pi, handlers, busHandlers } = createMockPi();+ factory(pi);+ expect(handlers.size).toBe(0);+ expect(busHandlers.size).toBe(0);++ // Loaded paths are consulted per invocation, so a /reload after the+ // file-based integration is removed or disabled re-enables the built-in.+ loadedPaths = [];+ const second = createMockPi();+ factory(second.pi);+ expect(second.handlers.size).toBeGreaterThan(0);+ });++ it("ignores events from sessions other than the one it bound to", async () => {+ const tempDir = join(tmpdir(), `hrd-${Math.random().toString(36).slice(2, 8)}`);+ mkdirSync(tempDir, { recursive: true });+ cleanupPaths.push(tempDir);+ const socketPath = join(tempDir, "h.sock");++ const { server, requests, waitForRequests } = await startFakeHerdrServer(socketPath);+ cleanupServers.push(server);++ process.env.HERDR_ENV = "1";+ process.env.HERDR_SOCKET_PATH = socketPath;+ process.env.HERDR_PANE_ID = "w1:p1";++ const { pi, handlers } = createMockPi();+ herdrAgentStateExtension(pi);++ const parentSessionManager = { getSessionFile: () => "/tmp/parent.jsonl", getSessionId: () => "parent" };+ const childSessionManager = { getSessionFile: () => "/tmp/child.jsonl", getSessionId: () => "child" };+ const parentCtx = { sessionManager: parentSessionManager };+ const childCtx = { sessionManager: childSessionManager };++ handlers.get("session_start")?.[0]?.({ type: "session_start", reason: "startup" }, parentCtx);+ await waitForRequests(1);+ expect(requests[0]?.params.agent_session_path).toBe("/tmp/parent.jsonl");++ // Inline RLM children rebind the same handlers with their own ctx; their+ // events must not flip the pane state or release the parent's pane.+ handlers.get("agent_start")?.[0]?.({ type: "agent_start" }, childCtx);+ await handlers.get("session_shutdown")?.[0]?.({ type: "session_shutdown", reason: "quit" }, childCtx);+ await new Promise((resolve) => setTimeout(resolve, 50));+ expect(requests).toHaveLength(1);++ // The bound parent still reports normally.+ handlers.get("agent_start")?.[0]?.({ type: "agent_start" }, parentCtx);+ await waitForRequests(2);+ expect(requests[1]?.params.state).toBe("working");+ });++ it("reports lifecycle state to the herdr socket", async () => {+ // Unix socket paths must stay under ~104 chars; use a short base dir.+ const tempDir = join(tmpdir(), `hrd-${Math.random().toString(36).slice(2, 8)}`);+ mkdirSync(tempDir, { recursive: true });+ cleanupPaths.push(tempDir);+ const socketPath = join(tempDir, "h.sock");++ const { server, requests, waitForRequests } = await startFakeHerdrServer(socketPath);+ cleanupServers.push(server);++ process.env.HERDR_ENV = "1";+ process.env.HERDR_SOCKET_PATH = socketPath;+ process.env.HERDR_PANE_ID = "w1:p1";+ process.env.HERDR_PI_IDLE_DEBOUNCE_MS = "10";+ // Isolate from any real agent dir that may contain the file-based integration.+ process.env.PRIME_AGENT_CODING_AGENT_DIR = tempDir;++ const { pi, handlers } = createMockPi();+ herdrAgentStateExtension(pi);++ expect(handlers.has("session_start")).toBe(true);+ expect(handlers.has("agent_start")).toBe(true);+ expect(handlers.has("agent_end")).toBe(true);+ expect(handlers.has("session_shutdown")).toBe(true);++ const ctx = {+ sessionManager: {+ getSessionFile: () => "/tmp/session.jsonl",+ getSessionId: () => "session-1",+ },+ };++ handlers.get("session_start")?.[0]?.({ type: "session_start", reason: "startup" }, ctx);+ await waitForRequests(1);+ expect(requests[0]?.method).toBe("pane.report_agent");+ expect(requests[0]?.params.agent).toBe("prime-agent");+ expect(requests[0]?.params.pane_id).toBe("w1:p1");+ expect(requests[0]?.params.state).toBe("idle");+ expect(requests[0]?.params.agent_session_path).toBe("/tmp/session.jsonl");++ handlers.get("agent_start")?.[0]?.({ type: "agent_start" }, ctx);+ await waitForRequests(2);+ expect(requests[1]?.params.state).toBe("working");++ handlers.get("agent_end")?.[0]?.({ type: "agent_end", messages: [] }, ctx);+ await waitForRequests(3);+ expect(requests[2]?.params.state).toBe("idle");++ // Session replacement must not release: the successor session re-reports,+ // and a racing release could clear the successor's fresh report.+ await handlers.get("session_shutdown")?.[0]?.({ type: "session_shutdown", reason: "new" }, ctx);+ await new Promise((resolve) => setTimeout(resolve, 50));+ expect(requests).toHaveLength(3);++ await handlers.get("session_shutdown")?.[0]?.({ type: "session_shutdown", reason: "quit" }, ctx);+ await waitForRequests(4);+ expect(requests[3]?.method).toBe("pane.release_agent");+ expect(requests[3]?.params.agent).toBe("prime-agent");+ });++ it("unsubscribes the shared-bus herdr:blocked listener on shutdown", async () => {+ const tempDir = join(tmpdir(), `hrd-${Math.random().toString(36).slice(2, 8)}`);+ mkdirSync(tempDir, { recursive: true });+ cleanupPaths.push(tempDir);+ const socketPath = join(tempDir, "h.sock");++ const { server } = await startFakeHerdrServer(socketPath);+ cleanupServers.push(server);++ process.env.HERDR_ENV = "1";+ process.env.HERDR_SOCKET_PATH = socketPath;+ process.env.HERDR_PANE_ID = "w1:p1";++ const { pi, handlers, busHandlers } = createMockPi();+ herdrAgentStateExtension(pi);+ expect(busHandlers.get("herdr:blocked")).toHaveLength(1);++ const ctx = { sessionManager: { getSessionFile: () => undefined, getSessionId: () => "s" } };+ // Replacement shutdowns must also unsubscribe, or every /reload and /new+ // stacks another live listener on the shared bus.+ await handlers.get("session_shutdown")?.[0]?.({ type: "session_shutdown", reason: "new" }, ctx);+ expect(busHandlers.get("herdr:blocked")).toHaveLength(0);+ });++ it("reports working when the session starts mid-turn (reload)", async () => {+ const tempDir = join(tmpdir(), `hrd-${Math.random().toString(36).slice(2, 8)}`);+ mkdirSync(tempDir, { recursive: true });+ cleanupPaths.push(tempDir);+ const socketPath = join(tempDir, "h.sock");++ const { server, requests, waitForRequests } = await startFakeHerdrServer(socketPath);+ cleanupServers.push(server);++ process.env.HERDR_ENV = "1";+ process.env.HERDR_SOCKET_PATH = socketPath;+ process.env.HERDR_PANE_ID = "w1:p1";+ process.env.HERDR_PI_IDLE_DEBOUNCE_MS = "10";++ const { pi, handlers } = createMockPi();+ herdrAgentStateExtension(pi);++ // Reload mid-turn: the fresh reporter's session_start sees a busy session.+ const ctx = {+ sessionManager: { getSessionFile: () => undefined, getSessionId: () => "s" },+ isIdle: () => false,+ };+ handlers.get("session_start")?.[0]?.({ type: "session_start", reason: "reload" }, ctx);+ await waitForRequests(1);+ expect(requests[0]?.params.state).toBe("working");++ // The turn's real end must still be honored (agentActive was seeded).+ handlers.get("agent_end")?.[0]?.({ type: "agent_end", messages: [] }, ctx);+ await waitForRequests(2);+ expect(requests[1]?.params.state).toBe("idle");+ });++ it("settles the retry hold when a blocked event interrupts it", async () => {+ const tempDir = join(tmpdir(), `hrd-${Math.random().toString(36).slice(2, 8)}`);+ mkdirSync(tempDir, { recursive: true });+ cleanupPaths.push(tempDir);+ const socketPath = join(tempDir, "h.sock");++ const { server, requests, waitForRequests } = await startFakeHerdrServer(socketPath);+ cleanupServers.push(server);++ process.env.HERDR_ENV = "1";+ process.env.HERDR_SOCKET_PATH = socketPath;+ process.env.HERDR_PANE_ID = "w1:p1";+ process.env.HERDR_PI_IDLE_DEBOUNCE_MS = "10";++ const { pi, handlers, busHandlers } = createMockPi();+ herdrAgentStateExtension(pi);++ const ctx = { sessionManager: { getSessionFile: () => undefined, getSessionId: () => "s" } };+ handlers.get("session_start")?.[0]?.({ type: "session_start", reason: "startup" }, ctx);+ handlers.get("agent_start")?.[0]?.({ type: "agent_start" }, ctx);+ // End with a retryable provider error: enters the retry hold (working).+ handlers.get("agent_end")?.[0]?.(+ {+ type: "agent_end",+ messages: [{ role: "assistant", stopReason: "error", errorMessage: "rate limit exceeded" }],+ },+ ctx,+ );+ // A blocked event lands during the hold, cancelling the retry timer...+ const blocked = busHandlers.get("herdr:blocked")?.[0];+ blocked?.({ active: true, label: "permission needed" });+ // ...and when the block lifts, the pane must settle to blocked (failed+ // retry), not stick at working forever. Intermediate states coalesce in+ // the latest-wins queue, so assert on the settled final report.+ blocked?.({ active: false });++ await waitForRequests(2);+ await new Promise((resolve) => setTimeout(resolve, 100));+ const finalState = requests.at(-1)?.params.state;+ expect(finalState).toBe("blocked");+ expect(requests.at(-1)?.params.message).toContain("rate limit");+ });++ it("holds working through any error end until the retry grace settles", async () => {+ const tempDir = join(tmpdir(), `hrd-${Math.random().toString(36).slice(2, 8)}`);+ mkdirSync(tempDir, { recursive: true });+ cleanupPaths.push(tempDir);+ const socketPath = join(tempDir, "h.sock");++ const { server, requests, waitForRequests } = await startFakeHerdrServer(socketPath);+ cleanupServers.push(server);++ process.env.HERDR_ENV = "1";+ process.env.HERDR_SOCKET_PATH = socketPath;+ process.env.HERDR_PANE_ID = "w1:p1";+ process.env.HERDR_PI_IDLE_DEBOUNCE_MS = "10";+ process.env.HERDR_PI_RETRY_GRACE_MS = "30";++ const { pi, handlers } = createMockPi();+ herdrAgentStateExtension(pi);++ const ctx = { sessionManager: { getSessionFile: () => undefined, getSessionId: () => "s" } };+ handlers.get("session_start")?.[0]?.({ type: "session_start", reason: "startup" }, ctx);+ handlers.get("agent_start")?.[0]?.({ type: "agent_start" }, ctx);+ // The agent's auto-retry classifies almost every provider error as+ // retryable, so an error the old pattern list missed must still hold+ // working (not flip idle) while a retry may be pending.+ handlers.get("agent_end")?.[0]?.(+ {+ type: "agent_end",+ messages: [{ role: "assistant", stopReason: "error", errorMessage: "unexpected provider failure xyz" }],+ },+ ctx,+ );++ // No retry arrives: after the grace window the pane settles to blocked+ // with the error message, never reporting idle in between.+ await waitForRequests(3);+ expect(requests.map((r) => r.params.state)).toEqual(["idle", "working", "blocked"]);+ expect(requests.at(-1)?.params.message).toContain("unexpected provider failure");+ });++ it("sends no reports after quit release", async () => {+ const tempDir = join(tmpdir(), `hrd-${Math.random().toString(36).slice(2, 8)}`);+ mkdirSync(tempDir, { recursive: true });+ cleanupPaths.push(tempDir);+ const socketPath = join(tempDir, "h.sock");++ const { server, requests, waitForRequests } = await startFakeHerdrServer(socketPath);+ cleanupServers.push(server);++ process.env.HERDR_ENV = "1";+ process.env.HERDR_SOCKET_PATH = socketPath;+ process.env.HERDR_PANE_ID = "w1:p1";++ const { pi, handlers } = createMockPi();+ herdrAgentStateExtension(pi);++ const ctx = { sessionManager: { getSessionFile: () => undefined, getSessionId: () => "s" } };+ handlers.get("session_start")?.[0]?.({ type: "session_start", reason: "startup" }, ctx);+ handlers.get("agent_start")?.[0]?.({ type: "agent_start" }, ctx);+ // Quit while the working report may still be in flight; the release must+ // be the final write, with no report reclaiming the pane afterwards.+ await handlers.get("session_shutdown")?.[0]?.({ type: "session_shutdown", reason: "quit" }, ctx);+ handlers.get("agent_start")?.[0]?.({ type: "agent_start" }, ctx);++ await waitForRequests(2);+ await new Promise((resolve) => setTimeout(resolve, 100));+ // Still-queued reports are dropped by the release, so the exact report+ // count depends on send timing; the invariant is that the release is the+ // last write and nothing reclaims the pane after it.+ expect(requests.at(-1)?.method).toBe("pane.release_agent");+ expect(requests.filter((r) => r.method === "pane.release_agent")).toHaveLength(1);+ });++ it("silences a replaced instance without releasing the pane", async () => {+ const tempDir = join(tmpdir(), `hrd-${Math.random().toString(36).slice(2, 8)}`);+ mkdirSync(tempDir, { recursive: true });+ cleanupPaths.push(tempDir);+ const socketPath = join(tempDir, "h.sock");++ const { server, requests, waitForRequests } = await startFakeHerdrServer(socketPath);+ cleanupServers.push(server);++ process.env.HERDR_ENV = "1";+ process.env.HERDR_SOCKET_PATH = socketPath;+ process.env.HERDR_PANE_ID = "w1:p1";++ const { pi, handlers } = createMockPi();+ herdrAgentStateExtension(pi);++ const ctx = { sessionManager: { getSessionFile: () => undefined, getSessionId: () => "s" } };+ handlers.get("session_start")?.[0]?.({ type: "session_start", reason: "startup" }, ctx);+ await waitForRequests(1);++ // Replacement shutdown: no release (the successor re-reports), and the+ // old instance must go quiet - a late report with its process-wide seq+ // would outrank and stomp the successor's state.+ await handlers.get("session_shutdown")?.[0]?.({ type: "session_shutdown", reason: "new" }, ctx);+ handlers.get("agent_start")?.[0]?.({ type: "agent_start" }, ctx);+ await new Promise((resolve) => setTimeout(resolve, 100));++ expect(requests).toHaveLength(1);+ expect(requests.some((r) => r.method === "pane.release_agent")).toBe(false);+ });++ it("keeps seq monotonically increasing across extension instances", async () => {+ const tempDir = join(tmpdir(), `hrd-${Math.random().toString(36).slice(2, 8)}`);+ mkdirSync(tempDir, { recursive: true });+ cleanupPaths.push(tempDir);+ const socketPath = join(tempDir, "h.sock");++ const { server, requests, waitForRequests } = await startFakeHerdrServer(socketPath);+ cleanupServers.push(server);++ process.env.HERDR_ENV = "1";+ process.env.HERDR_SOCKET_PATH = socketPath;+ process.env.HERDR_PANE_ID = "w1:p1";+ process.env.PRIME_AGENT_CODING_AGENT_DIR = tempDir;++ const ctx = { sessionManager: { getSessionFile: () => undefined, getSessionId: () => "s" } };++ // Two instances, as after a session replacement: the successor's seq must+ // exceed everything the predecessor sent, or herdr drops its reports.+ const first = createMockPi();+ herdrAgentStateExtension(first.pi);+ first.handlers.get("session_start")?.[0]?.({ type: "session_start", reason: "startup" }, ctx);+ await waitForRequests(1);++ const second = createMockPi();+ herdrAgentStateExtension(second.pi);+ second.handlers.get("session_start")?.[0]?.({ type: "session_start", reason: "new" }, ctx);+ await waitForRequests(2);++ const seqs = requests.map((r) => r.params.seq as number);+ expect(seqs[1]).toBeGreaterThan(seqs[0]);+ });+});