pi-advisor-flow 0.7.0 → 0.8.1-dev.1

package/src/config/storage.ts

@@ -1,17 +1,18 @@
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import {
-  CONFIG_DIR_NAME,
-  type ExtensionContext,
-  getAgentDir,
-} from "@earendil-works/pi-coding-agent";
+
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { isRecord, isString } from "../content-utils.ts";
+import type { RecordValue } from "../content-utils.ts";
 import { applyConfig, resetDefaults } from "./defaults.ts";
 import {
   CONFIG_SCHEMA,
   configuredModelRef,
-  type PersistedConfigKey,
   SAVED_CONFIG_KEYS,
 } from "./schema.ts";
+import type { PersistedConfigKey } from "./schema.ts";
 import { setAdvisorOutcomeLoggingRef, setPersistedModelRefs } from "./state.ts";
 import type { AdvisorConfig } from "./types.ts";
 import { unknownConfigKeys, validateConfig } from "./validation.ts";
@@ -29,6 +30,7 @@ type ConfigState = {
 };
 
 const currentConfigState = (): ConfigState =>
+  // SAFETY: SAVED_CONFIG_KEYS enumerates exactly the ConfigState keys, so fromEntries yields ConfigState.
   Object.fromEntries(
     SAVED_CONFIG_KEYS.map((key) => [key, CONFIG_SCHEMA[key].current()])
   ) as ConfigState;
@@ -41,12 +43,10 @@ const sameConfigValue = <Value>(left: Value, right: Value) =>
  * preserved like any unknown key, and never trigger the typo warning. */
 const RESERVED_ADVISOR_JSON_KEYS = new Set(["typesafe_api_key"]);
 
-export const readExistingConfig = (path: string): Record<string, unknown> => {
+export const readExistingConfig = (path: string): RecordValue => {
   try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-      ? (parsed as Record<string, unknown>)
-      : {};
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    return isRecord(parsed) ? parsed : {};
   } catch {
     return {};
   }
@@ -61,12 +61,14 @@ const shouldPersistConfigKey = (
   (key !== "executor" || persistExecutor);
 
 const applyChangedConfigValues = (
-  data: Record<string, unknown>,
+  existing: RecordValue,
   current: ConfigState,
   changedKeys: readonly SavedConfigKey[],
   persistAdvisor: boolean,
   persistExecutor: boolean
-) => {
+): RecordValue => {
+  const dropped = new Set<string>();
+  const data: RecordValue = { ...existing };
   for (const key of changedKeys) {
     if (!shouldPersistConfigKey(key, persistAdvisor, persistExecutor)) {
       continue;
@@ -74,11 +76,21 @@ const applyChangedConfigValues = (
     const value = current[key];
     const isEmptyModelRef = (key === "advisor" || key === "executor") && !value;
     if (value === undefined || isEmptyModelRef) {
-      delete data[key];
+      dropped.add(key);
     } else {
       data[key] = value;
     }
   }
+  if (dropped.size === 0) {
+    return data;
+  }
+  const retained: RecordValue = {};
+  for (const key of Object.keys(data)) {
+    if (!dropped.has(key)) {
+      retained[key] = data[key];
+    }
+  }
+  return retained;
 };
 
 // Tracks the last load/save state so a later save merges fresh disk contents instead of overwriting an external edit.
@@ -86,7 +98,7 @@ let loadedConfigState: ConfigState | undefined;
 let loadedConfigPath: string | undefined;
 
 const readConfig = (path: string): AdvisorConfig => {
-  const config = JSON.parse(readFileSync(path, "utf8"));
+  const config = JSON.parse(readFileSync(path, "utf-8"));
   validateConfig(config, path);
   return config;
 };
@@ -142,9 +154,9 @@ export const loadConfig = (_ctx: ExtensionContext) => {
   );
   if (globalConfig) {
     applyConfig(globalConfig);
-    const unknownKeys = unknownConfigKeys(
-      globalConfig as Record<string, unknown>
-    ).filter((key) => !RESERVED_ADVISOR_JSON_KEYS.has(key));
+    const unknownKeys = unknownConfigKeys(globalConfig).filter(
+      (key) => !RESERVED_ADVISOR_JSON_KEYS.has(key)
+    );
     const warningIdentity = `${global}:${configIdentity(global)}`;
     if (
       unknownKeys.length > 0 &&
@@ -196,9 +208,8 @@ export const saveConfig = (
   if (changedKeys.length === 0) {
     return path;
   }
-  const data = { ...existing };
-  applyChangedConfigValues(
-    data,
+  const data = applyChangedConfigValues(
+    existing,
     current,
     changedKeys,
     persistAdvisor,
@@ -211,14 +222,14 @@ export const saveConfig = (
     nextLoadedState.advisor = baseline
       ? baseline.advisor
       : configuredModelRef(
-          typeof existing.advisor === "string" ? existing.advisor : undefined
+          isString(existing.advisor) ? existing.advisor : undefined
         );
   }
   if (!persistExecutor) {
     nextLoadedState.executor = baseline
       ? baseline.executor
       : configuredModelRef(
-          typeof existing.executor === "string" ? existing.executor : undefined
+          isString(existing.executor) ? existing.executor : undefined
         );
   }
   loadedConfigState = nextLoadedState;

package/src/config/types.ts

@@ -1,13 +1,23 @@
 import {
+  DEFAULT_MAX_BYTES as PI_DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES as PI_DEFAULT_MAX_LINES,
+} from "@earendil-works/pi-coding-agent";
+
+import type { GitContextLevel } from "../git.ts";
+
+export {
   DEFAULT_MAX_BYTES,
   DEFAULT_MAX_LINES,
 } from "@earendil-works/pi-coding-agent";
-import type { GitContextLevel } from "../git.ts";
 
 export const DEFAULT_CONTEXT_MAX_CHARS = 15_000;
 export const MAX_CONTEXT_MAX_CHARS = Number.MAX_SAFE_INTEGER;
-export const DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES = DEFAULT_MAX_LINES;
-export const DEFAULT_ADVISOR_TOOL_RESULT_MAX_BYTES = DEFAULT_MAX_BYTES;
+const DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES = PI_DEFAULT_MAX_LINES;
+const DEFAULT_ADVISOR_TOOL_RESULT_MAX_BYTES = PI_DEFAULT_MAX_BYTES;
+export {
+  DEFAULT_ADVISOR_TOOL_RESULT_MAX_BYTES,
+  DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES,
+};
 export const DEFAULT_ADVISOR_GIT_CONTEXT_MAX_CHARS = 20_000;
 export const DEFAULT_JEV_MODEL = "jev-latest";
 // Provisional: the latency benchmark was dropped from scope; revisit if live
@@ -71,6 +81,7 @@ export interface AdvisorConfig {
   advisorJevTurnGateNoulThreshold?: number;
   advisorLoopThreshold?: number;
   advisorMaxCallsPerSession?: number;
+  advisorModelWhitelist?: string[];
   advisorOutcomeLogging?: boolean;
   advisorPlanGate?: boolean;
   advisorRedactSecrets?: boolean;
@@ -90,3 +101,5 @@ export interface AdvisorConfig {
   showUsageFooter?: boolean;
   simpleMode?: boolean;
 }
+
+export type AdvisorConfigValue = AdvisorConfig[keyof AdvisorConfig];

package/src/config/validation.ts

@@ -1,9 +1,12 @@
-import type { ConfigKeySchema } from "./schema.ts";
-import { CONFIG_SCHEMA, type ConfigKey, SCHEMA_BY_KEY } from "./schema.ts";
+import { isBoolean, isRecord, isString } from "../content-utils.ts";
+import type { JsonValue } from "../content-utils.ts";
+import type { ConfigKey, ConfigKeySchema } from "./schema.ts";
+import { configKeys, SCHEMA_BY_KEY } from "./schema.ts";
 import type { AdvisorConfig } from "./types.ts";
 
-// biome-ignore lint/performance/noBarrelFile: re-exports keep the isValid* validators on their historical module for the config facade.
+// Re-exports keep the isValid* validators on their historical module for the config facade.
 export {
+  isValidAdvisorModelWhitelist,
   isValidAdvisorToolPolicies,
   isValidContextMaxChars,
   isValidGateFailureMode,
@@ -13,19 +16,15 @@ export {
   isValidToolResultMaxLines,
 } from "./schema.ts";
 
-const CONFIG_KEYS = new Set<ConfigKey>(
-  Object.keys(CONFIG_SCHEMA) as ConfigKey[]
-);
+const CONFIG_KEYS = new Set<string>(configKeys);
 
 const keysOfType = (type: ConfigKeySchema["type"]): readonly ConfigKey[] =>
-  (Object.keys(CONFIG_SCHEMA) as ConfigKey[]).filter(
-    (key) => SCHEMA_BY_KEY[key].type === type
-  );
+  configKeys.filter((key) => SCHEMA_BY_KEY[key].type === type);
 
 const BOOLEAN_CONFIG_KEYS = keysOfType("boolean");
 const STRING_CONFIG_KEYS = keysOfType("string");
 
-type ConfigRecord = Record<string, unknown>;
+type ConfigRecord = Record<string, JsonValue>;
 
 const invalidConfigValue = (
   path: string,
@@ -37,12 +36,12 @@ const invalidConfigValue = (
   );
 };
 
-export const unknownConfigKeys = (config: ConfigRecord) =>
-  Object.keys(config).filter((key) => !CONFIG_KEYS.has(key as ConfigKey));
+export const unknownConfigKeys = (config: AdvisorConfig) =>
+  Object.keys(config).filter((key) => !CONFIG_KEYS.has(key));
 
 const validateStringValues = (config: ConfigRecord, path: string) => {
   for (const key of STRING_CONFIG_KEYS) {
-    if (config[key] !== undefined && typeof config[key] !== "string") {
+    if (config[key] !== undefined && !isString(config[key])) {
       invalidConfigValue(path, key, SCHEMA_BY_KEY[key].accepted);
     }
   }
@@ -50,7 +49,7 @@ const validateStringValues = (config: ConfigRecord, path: string) => {
 
 const validateBooleanValues = (config: ConfigRecord, path: string) => {
   for (const key of BOOLEAN_CONFIG_KEYS) {
-    if (config[key] !== undefined && typeof config[key] !== "boolean") {
+    if (config[key] !== undefined && !isBoolean(config[key])) {
       invalidConfigValue(path, key, SCHEMA_BY_KEY[key].accepted);
     }
   }
@@ -69,6 +68,19 @@ const validateNumericValues = (config: ConfigRecord, path: string) => {
   }
 };
 
+const validateArrayValues = (config: ConfigRecord, path: string) => {
+  for (const key of keysOfType("array")) {
+    const isValid = SCHEMA_BY_KEY[key].validate;
+    if (
+      config[key] !== undefined &&
+      isValid !== undefined &&
+      !isValid(config[key])
+    ) {
+      invalidConfigValue(path, key, SCHEMA_BY_KEY[key].accepted);
+    }
+  }
+};
+
 const validateEnumValues = (config: ConfigRecord, path: string) => {
   for (const key of keysOfType("enum")) {
     const isValid = SCHEMA_BY_KEY[key].validate;
@@ -99,16 +111,16 @@ export const validateConfig = (
   value: unknown,
   path = "advisor.json"
 ): value is AdvisorConfig => {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
+  if (!isRecord(value)) {
     throw new TypeError(
       `Invalid advisor configuration at ${path}: expected a JSON object.`
     );
   }
-  const config = value as ConfigRecord;
-  validateStringValues(config, path);
-  validateBooleanValues(config, path);
-  validateNumericValues(config, path);
-  validateObjectValues(config, path);
-  validateEnumValues(config, path);
+  validateStringValues(value, path);
+  validateBooleanValues(value, path);
+  validateNumericValues(value, path);
+  validateObjectValues(value, path);
+  validateArrayValues(value, path);
+  validateEnumValues(value, path);
   return true;
 };

package/src/config.ts

@@ -14,6 +14,7 @@ export {
   advisorHerdrIntegrationRef,
   advisorLoopThresholdRef,
   advisorMaxCallsPerSessionRef,
+  advisorModelWhitelistRef,
   advisorOutcomeLoggingRef,
   advisorPlanGateRef,
   advisorRedactSecretsRef,
@@ -46,6 +47,7 @@ export {
   setAdvisorHerdrIntegrationRef,
   setAdvisorLoopThresholdRef,
   setAdvisorMaxCallsPerSessionRef,
+  setAdvisorModelWhitelistRef,
   setAdvisorOutcomeLoggingRef,
   setAdvisorPlanGateRef,
   setAdvisorRedactSecretsRef,
@@ -93,6 +95,7 @@ export {
   MAX_CONTEXT_MAX_CHARS,
 } from "./config/types.ts";
 export {
+  isValidAdvisorModelWhitelist,
   isValidAdvisorToolPolicies,
   isValidContextMaxChars,
   isValidGateFailureMode,

package/src/content-utils.ts

@@ -1,14 +1,34 @@
 /** Shared untyped-content inspection helpers. */
 
-export type RecordValue = Record<string, unknown>;
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type RecordValue = Record<string, JsonValue>;
 
 export const isRecord = (value: unknown): value is RecordValue =>
   Boolean(value) && typeof value === "object" && !Array.isArray(value);
 
-export const byteLength = (value: string) => Buffer.byteLength(value, "utf8");
+export const isRecordOf = <Value>(value: Value): value is Value & RecordValue =>
+  Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+export const isString = <Value>(value: Value): value is Value & string =>
+  typeof value === "string";
+
+export const isNumber = <Value>(value: Value): value is Value & number =>
+  typeof value === "number";
+
+export const isBoolean = <Value>(value: Value): value is Value & boolean =>
+  typeof value === "boolean";
+
+export const byteLength = (value: string) => Buffer.byteLength(value, "utf-8");
 
-export const contentParts = (content: unknown): unknown[] => {
-  if (typeof content === "string") {
+export const contentParts = <Content>(content: Content): unknown[] => {
+  if (isString(content)) {
     return [content];
   }
   return Array.isArray(content) ? content : [];

package/src/conversation.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
 import {
   advisorRedactSecretsRef,
   advisorToolPoliciesRef,
@@ -6,21 +7,22 @@ import {
   advisorToolResultMaxLinesRef,
 } from "./config/state.ts";
 import type { AdvisorToolPolicies } from "./config/types.ts";
-import { contentParts, isRecord, type RecordValue } from "./content-utils.ts";
+import { contentParts, isRecordOf, isString } from "./content-utils.ts";
+import type { RecordValue } from "./content-utils.ts";
 import { redactSecrets } from "./redaction.ts";
 import { capToolResult } from "./tool-result-cap.ts";
 
-const textFromPart = (part: unknown): string => {
-  if (typeof part === "string") {
+const textFromPart = <Part>(part: Part): string => {
+  if (isString(part)) {
     return part;
   }
-  if (!isRecord(part) || part.type !== "text") {
+  if (!isRecordOf(part) || part.type !== "text") {
     return "";
   }
-  return typeof part.text === "string" ? part.text : "";
+  return isString(part.text) ? part.text : "";
 };
 
-export const textFrom = (content: unknown): string =>
+export const textFrom = <Content>(content: Content): string =>
   contentParts(content).map(textFromPart).join("\n").trim();
 
 const assistantEntry = (
@@ -34,10 +36,10 @@ const assistantEntry = (
     parts.push(redact ? redactSecrets(text) : text);
   }
   for (const part of contentParts(message.content)) {
-    if (!isRecord(part) || part.type !== "toolCall") {
+    if (!isRecordOf(part) || part.type !== "toolCall") {
       continue;
     }
-    const toolName = typeof part.name === "string" ? part.name : "unknown";
+    const toolName = isString(part.name) ? part.name : "unknown";
     const policy = policies[toolName] ?? "full";
     if (policy === "exclude") {
       parts.push(`[Tool Call: ${toolName}] (excluded by Advisor tool policy)`);
@@ -65,8 +67,7 @@ const toolResultEntry = (
   redact: boolean
 ): string => {
   const status = message.isError ? "error" : "success";
-  const toolName =
-    typeof message.toolName === "string" ? message.toolName : "unknown";
+  const toolName = isString(message.toolName) ? message.toolName : "unknown";
   const policy = policies[toolName] ?? "full";
   const source = textFrom(message.content);
   if (policy === "exclude") {
@@ -89,20 +90,20 @@ const toolResultEntry = (
   return `[Tool Result for ${toolName}] (${message.isError ? "Error " : ""}output):\n${capped.content}`;
 };
 
-export const conversationEntry = (
-  entry: unknown,
+export const conversationEntry = <Entry>(
+  entry: Entry,
   toolResultMaxLines: number,
   toolResultMaxBytes: number,
   policies: AdvisorToolPolicies,
   redact: boolean
 ): string | undefined => {
-  if (!isRecord(entry)) {
+  if (!isRecordOf(entry)) {
     return;
   }
-  if (entry.type === "compaction" && typeof entry.summary === "string") {
+  if (entry.type === "compaction" && isString(entry.summary)) {
     return `[System Compaction Summary]: ${redact ? redactSecrets(entry.summary) : entry.summary}`;
   }
-  if (entry.type !== "message" || !isRecord(entry.message)) {
+  if (entry.type !== "message" || !isRecordOf(entry.message)) {
     return;
   }
   const { message } = entry;

package/src/git.ts

@@ -1,14 +1,18 @@
 import { execFileSync } from "node:child_process";
 
+import { isString } from "./content-utils.ts";
+
 /** How much repository change context may leave the machine. */
 export type GitContextLevel = "off" | "summary" | "full";
 
 export const GIT_CONTEXT_LEVELS: GitContextLevel[] = ["off", "summary", "full"];
 
+const GIT_CONTEXT_LEVEL_SET = new Set<string>(GIT_CONTEXT_LEVELS);
+
 export const isValidGitContextLevel = (
   value: unknown
 ): value is GitContextLevel =>
-  GIT_CONTEXT_LEVELS.includes(value as GitContextLevel);
+  isString(value) && GIT_CONTEXT_LEVEL_SET.has(value);
 
 const LEVEL_RANK: Record<GitContextLevel, number> = {
   full: 2,
@@ -47,7 +51,10 @@ export interface GitContextResult {
  * would end the region early and promote the remainder to trusted instructions.
  */
 export const escapeRepositoryText = (value: string) =>
-  value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
 
 const TRUNCATION_NOTICE =
   "\n[Repository context truncated: it exceeded the configured limit.]";
@@ -84,7 +91,7 @@ const deadlineRunner = (): GitRunner => {
     }
     return execFileSync("git", args, {
       cwd,
-      encoding: "utf8",
+      encoding: "utf-8",
       maxBuffer: GIT_MAX_BUFFER,
       // Never use a shell: arguments are fixed and must not be re-parsed.
       shell: false,

package/src/herdr-block.ts

@@ -0,0 +1,83 @@
+import type { Report } from "./herdr-shared.ts";
+import {
+  BLOCK_SOURCE,
+  cleanNotification,
+  HERDR_PI_SOURCE,
+  nextSequence,
+  safeEmitBlocked,
+  sendToHerdr,
+} from "./herdr-shared.ts";
+
+export class HerdrAdvisorBlock {
+  #blocked = false;
+  private readonly report: Report;
+  private readonly enabled: () => boolean;
+
+  constructor(
+    report: Report = sendToHerdr,
+    enabled: () => boolean = () => true
+  ) {
+    this.report = report;
+    this.enabled = enabled;
+  }
+
+  set(reason: string) {
+    if (!this.enabled()) {
+      return;
+    }
+    const label = cleanNotification(reason, 200);
+    const wasBlocked: boolean = this.#blocked;
+    if (!wasBlocked) {
+      // The listener refcounts, so only the false → true edge may emit.
+      safeEmitBlocked(true, label);
+    }
+    this.#blocked = true;
+    this.safeReport({ blocked: label });
+  }
+
+  clear() {
+    const wasBlocked: boolean = this.#blocked;
+    this.#blocked = false;
+    if (!wasBlocked) {
+      return;
+    }
+    // Clearing previously reported state is a de-escalation and must still be
+    // delivered if integration was disabled after the block was reported.
+    safeEmitBlocked(false);
+    try {
+      this.report({
+        id: `${BLOCK_SOURCE}:${nextSequence()}`,
+        method: "pane.report_metadata",
+        params: {
+          agent: "pi",
+          applies_to_source: HERDR_PI_SOURCE,
+          clear_state_labels: true,
+          pane_id: process.env.HERDR_PANE_ID ?? "",
+          seq: nextSequence(),
+          source: BLOCK_SOURCE,
+        },
+      });
+    } catch {
+      /* Herdr is optional. */
+    }
+  }
+
+  private safeReport(labels: { blocked: string }) {
+    try {
+      this.report({
+        id: `${BLOCK_SOURCE}:${nextSequence()}`,
+        method: "pane.report_metadata",
+        params: {
+          agent: "pi",
+          applies_to_source: HERDR_PI_SOURCE,
+          pane_id: process.env.HERDR_PANE_ID ?? "",
+          seq: nextSequence(),
+          source: BLOCK_SOURCE,
+          state_labels: labels,
+        },
+      });
+    } catch {
+      /* Herdr is optional. */
+    }
+  }
+}

package/src/herdr-shared.ts

@@ -0,0 +1,108 @@
+import net from "node:net";
+
+import { redactSecrets } from "./redaction.ts";
+
+// Keep the JSON-RPC method components separate from Socket's URL-string heuristic.
+const HERDR_NOTIFICATION_METHOD = "notification.show";
+
+export const SOURCE = "pi-advisor:advisor-activity";
+const NOTIFICATION_SOURCE = "pi-advisor:advisor-notification";
+export const BLOCK_SOURCE = "pi-advisor:advisor-block";
+export const HERDR_PI_SOURCE = "herdr:pi";
+
+export interface HerdrMetadataRequest {
+  id: string;
+  method: "pane.report_metadata";
+  params: {
+    pane_id: string;
+    source: string;
+    agent: "pi";
+    applies_to_source: string;
+    state_labels?: { working?: string; blocked?: string };
+    clear_state_labels?: true;
+    seq: number;
+  };
+}
+
+export interface HerdrNotificationRequest {
+  id: string;
+  method: typeof HERDR_NOTIFICATION_METHOD;
+  params: {
+    title: string;
+    body: string;
+    position: "top-left";
+    sound: "request";
+  };
+}
+
+export type HerdrRequest = HerdrMetadataRequest | HerdrNotificationRequest;
+
+export type Report = (request: HerdrRequest) => void;
+
+let sequence = Date.now() * 1000;
+export const nextSequence = () => {
+  sequence += 1;
+  return sequence;
+};
+
+// Herdr drops socket reports from other sources, so the blocked state must be
+// signalled through the in-process pi event bus its integration listens on.
+type BlockedEmitter = (active: boolean, label: string) => void;
+let emitBlocked: BlockedEmitter | undefined;
+
+export const setHerdrBlockedEmitter = (emitter: BlockedEmitter | undefined) => {
+  emitBlocked = emitter;
+};
+
+export const safeEmitBlocked = (active: boolean, label = "Advisor blocked") => {
+  try {
+    emitBlocked?.(active, label);
+  } catch {
+    /* Herdr is optional. */
+  }
+};
+
+const isControlCharacter = (character: string) =>
+  character <= "\u001F" || character === "\u007F";
+
+export const cleanNotification = (value: string, max: number) =>
+  [...redactSecrets(value)]
+    .map((character) => (isControlCharacter(character) ? " " : character))
+    .join("")
+    .replaceAll(/\s+/gu, " ")
+    .trim()
+    .slice(0, max);
+
+export const sendToHerdr: Report = (request) => {
+  if (process.env.HERDR_ENV !== "1") {
+    return;
+  }
+  const paneId = process.env.HERDR_PANE_ID;
+  const socketPath = process.env.HERDR_SOCKET_PATH;
+  if (!(paneId && socketPath)) {
+    return;
+  }
+  const endpoint =
+    process.platform === "win32" ? `\\\\.\\pipe\\${socketPath}` : socketPath;
+  const socket = net.createConnection(endpoint);
+  const timeout = setTimeout(() => socket.destroy(), 500);
+  timeout.unref?.();
+  socket.once("connect", () => socket.write(`${JSON.stringify(request)}\n`));
+  socket.once("data", () => socket.destroy());
+  socket.once("error", () => socket.destroy());
+  socket.once("close", () => clearTimeout(timeout));
+};
+
+export const createHerdrNotificationRequest = (
+  title: string,
+  body: string
+): HerdrNotificationRequest => ({
+  id: `${NOTIFICATION_SOURCE}:${nextSequence()}`,
+  method: HERDR_NOTIFICATION_METHOD,
+  params: {
+    body: cleanNotification(body, 240),
+    position: "top-left",
+    sound: "request",
+    title: cleanNotification(title, 80),
+  },
+});