pi-advisor-flow 0.6.0 → 0.8.0

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),
+  },
+});