pi-advisor-flow 0.1.9 → 0.2.0

package/src/conversation.ts

@@ -1,53 +1,204 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  advisorToolResultMaxBytesRef,
+  advisorToolResultMaxLinesRef,
+  DEFAULT_ADVISOR_TOOL_RESULT_MAX_BYTES,
+  DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES,
+} from "./config.js";
 
-export const textFrom = (content: unknown): string => {
-  return (typeof content === "string" ? [content] : Array.isArray(content) ? content : [])
-    .map((part: unknown) =>
-      typeof part === "string"
-        ? part
-        : (part as { type?: string; text?: string })?.type === "text"
-        ? (part as { text?: string }).text ?? ""
-        : ""
-    )
-    .join("\n")
-    .trim();
-};
-
-export const recentConversation = (ctx: ExtensionContext, maxChars = 15000): string => {
-  if (maxChars === 0) return "";
-  const entries: string[] = [];
-  for (const entry of ctx.sessionManager.getBranch()) {
-    if (entry.type === "message") {
-      const msg = entry.message;
-      if (msg.role === "user") {
-        const text = textFrom(msg.content);
-        if (text) entries.push(`User: ${text}`);
-      } else if (msg.role === "assistant") {
-        const parts: string[] = [];
-        const text = textFrom(msg.content);
-        if (text) parts.push(text);
-        if (Array.isArray(msg.content)) {
-          for (const part of msg.content) {
-            if (part && typeof part === "object" && part.type === "toolCall") {
-              const tc = part as { name?: string; arguments?: unknown };
-              const argsStr = JSON.stringify(tc.arguments);
-              parts.push(`[Tool Call: ${tc.name}(${argsStr})]`);
-            }
-          }
-        }
-        if (parts.length > 0) {
-          entries.push(`Executor: ${parts.join("\n")}`);
-        }
-      } else if (msg.role === "toolResult" || (msg as any).role === "tool") {
-        const tr = msg as { toolName?: string; isError?: boolean; content?: unknown };
-        const text = textFrom(tr.content);
-        const status = tr.isError ? "Error " : "";
-        entries.push(`[Tool Result for ${tr.toolName || "unknown"}] (${status}output):\n${text}`);
-      }
-    } else if (entry.type === "compaction") {
-      entries.push(`[System Compaction Summary]: ${entry.summary}`);
+type RecordValue = Record<string, unknown>;
+
+const isRecord = (value: unknown): value is RecordValue =>
+  Boolean(value) && typeof value === "object";
+
+const contentParts = (content: unknown): unknown[] => {
+  if (typeof content === "string") {
+    return [content];
+  }
+  return Array.isArray(content) ? content : [];
+};
+
+const textFromPart = (part: unknown): string => {
+  if (typeof part === "string") {
+    return part;
+  }
+  if (!isRecord(part) || part.type !== "text") {
+    return "";
+  }
+  return typeof part.text === "string" ? part.text : "";
+};
+
+export const textFrom = (content: unknown): string =>
+  contentParts(content).map(textFromPart).join("\n").trim();
+
+const byteLength = (value: string) => Buffer.byteLength(value, "utf8");
+
+export interface ToolResultTruncation {
+  content: string;
+  omittedLines: number;
+  totalBytes: number;
+  totalLines: number;
+  truncated: boolean;
+}
+
+export const capToolResult = (
+  value: string,
+  maxLines = DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES,
+  maxBytes = DEFAULT_ADVISOR_TOOL_RESULT_MAX_BYTES
+): ToolResultTruncation => {
+  const lines = value.split("\n");
+  const totalLines = lines.length;
+  const totalBytes = byteLength(value);
+  if ((maxLines === 0 || maxBytes === 0) && value.length > 0) {
+    return {
+      content: "[Tool result omitted: configured limit is zero]",
+      omittedLines: totalLines,
+      totalBytes,
+      totalLines,
+      truncated: true,
+    };
+  }
+  if (totalLines <= maxLines && totalBytes <= maxBytes) {
+    return {
+      content: value,
+      omittedLines: 0,
+      totalBytes,
+      totalLines,
+      truncated: false,
+    };
+  }
+
+  const marker = "[... omitted tool-result section ...]";
+  const availableBytes = Math.max(0, maxBytes - byteLength(marker) - 2);
+  const headCount = Math.max(1, Math.floor(Math.max(1, maxLines - 1) / 2));
+  const tailCount = Math.max(1, Math.max(1, maxLines - 1) - headCount);
+  const head: string[] = [];
+  let headBytes = 0;
+  for (const line of lines.slice(0, headCount)) {
+    const next = headBytes + byteLength(line) + (head.length ? 1 : 0);
+    if (head.length && next > Math.ceil(availableBytes / 2)) {
+      break;
+    }
+    head.push(line);
+    headBytes = next;
+  }
+  const tail: string[] = [];
+  let tailBytes = 0;
+  const tailStart = Math.max(head.length, lines.length - tailCount);
+  for (const line of lines.slice(tailStart)) {
+    const next = tailBytes + byteLength(line) + (tail.length ? 1 : 0);
+    if (tail.length && next > Math.floor(availableBytes / 2)) {
+      break;
+    }
+    tail.push(line);
+    tailBytes = next;
+  }
+  const content = [...head, marker, ...tail].join("\n");
+  return {
+    content,
+    omittedLines: Math.max(0, totalLines - head.length - tail.length),
+    totalBytes,
+    totalLines,
+    truncated: true,
+  };
+};
+
+const assistantEntry = (message: RecordValue): string | undefined => {
+  const parts: string[] = [];
+  const text = textFrom(message.content);
+  if (text) {
+    parts.push(text);
+  }
+  for (const part of contentParts(message.content)) {
+    if (!isRecord(part) || part.type !== "toolCall") {
+      continue;
     }
+    parts.push(
+      `[Tool Call: ${String(part.name)}(${JSON.stringify(part.arguments)})]`
+    );
+  }
+  return parts.length > 0 ? `Executor: ${parts.join("\n")}` : undefined;
+};
+
+const toolResultEntry = (
+  message: RecordValue,
+  toolResultMaxLines: number,
+  toolResultMaxBytes: number
+): string => {
+  const status = message.isError ? "Error " : "";
+  const capped = capToolResult(
+    textFrom(message.content),
+    toolResultMaxLines,
+    toolResultMaxBytes
+  );
+  const toolName =
+    typeof message.toolName === "string" ? message.toolName : "unknown";
+  return `[Tool Result for ${toolName}] (${status}output):\n${capped.content}`;
+};
+
+const conversationEntry = (
+  entry: unknown,
+  toolResultMaxLines: number,
+  toolResultMaxBytes: number
+): string | undefined => {
+  if (!isRecord(entry)) {
+    return;
+  }
+  if (entry.type === "compaction" && typeof entry.summary === "string") {
+    return `[System Compaction Summary]: ${entry.summary}`;
+  }
+  if (entry.type !== "message" || !isRecord(entry.message)) {
+    return;
+  }
+  const message = entry.message;
+  if (message.role === "user") {
+    const text = textFrom(message.content);
+    return text ? `User: ${text}` : undefined;
+  }
+  if (message.role === "assistant") {
+    return assistantEntry(message);
   }
-  const joined = entries.join("\n\n");
-  return joined.length > maxChars ? joined.slice(-maxChars) : joined;
+  if (message.role === "toolResult" || message.role === "tool") {
+    return toolResultEntry(message, toolResultMaxLines, toolResultMaxBytes);
+  }
+};
+
+const selectRecentEntries = (entries: string[], maxChars: number): string => {
+  const separator = "\n\n";
+  const joined = entries.join(separator);
+  if (joined.length <= maxChars || maxChars === Number.MAX_SAFE_INTEGER) {
+    return joined;
+  }
+  const selected: string[] = [];
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const candidate = [entries[index], ...selected].join(separator);
+    if (candidate.length <= maxChars || selected.length === 0) {
+      selected.unshift(entries[index]);
+    } else {
+      break;
+    }
+  }
+  const omitted = entries.length - selected.length;
+  const suffix = selected.length
+    ? `${separator}${selected.join(separator)}`
+    : "";
+  return `[Older context omitted: ${omitted} complete entr${omitted === 1 ? "y" : "ies"}]${suffix}`;
+};
+
+export const recentConversation = (
+  ctx: ExtensionContext,
+  maxChars = 15_000,
+  toolResultMaxLines = advisorToolResultMaxLinesRef,
+  toolResultMaxBytes = advisorToolResultMaxBytesRef
+): string => {
+  if (maxChars === 0) {
+    return "";
+  }
+  const entries = ctx.sessionManager
+    .getBranch()
+    .map((entry) =>
+      conversationEntry(entry, toolResultMaxLines, toolResultMaxBytes)
+    )
+    .filter((entry): entry is string => entry !== undefined);
+  return selectRecentEntries(entries, maxChars);
 };

package/src/herdr.ts

@@ -1,13 +1,17 @@
 import net from "node:net";
+import { advisorHerdrIntegrationRef } from "./config.js";
 
 const SOURCE = "pi-advisor:advisor-activity";
 const BLOCK_SOURCE = "pi-advisor:advisor-block";
+const NOTIFICATION_SOURCE = "pi-advisor:advisor-notification";
 const HERDR_PI_SOURCE = "herdr:pi";
-let sequence = Date.now() * 1_000;
-
-const nextSequence = () => ++sequence;
+let sequence = Date.now() * 1000;
+const nextSequence = () => {
+  sequence += 1;
+  return sequence;
+};
 
-type HerdrRequest = {
+export interface HerdrMetadataRequest {
   id: string;
   method: "pane.report_metadata";
   params: {
@@ -19,17 +23,56 @@ type HerdrRequest = {
     clear_state_labels?: true;
     seq: number;
   };
-};
-
+}
+export interface HerdrNotificationRequest {
+  id: string;
+  method: "notification.show";
+  params: {
+    title: string;
+    body: string;
+    position: "top-left";
+    sound: "request";
+  };
+}
+export type HerdrRequest = HerdrMetadataRequest | HerdrNotificationRequest;
 type Report = (request: HerdrRequest) => void;
 
+const isControlCharacter = (character: string) =>
+  character <= "\u001f" || character === "\u007f";
+
+const cleanNotification = (value: string, max: number) =>
+  [...value]
+    .map((character) => (isControlCharacter(character) ? " " : character))
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, max);
+
+export const createHerdrNotificationRequest = (
+  title: string,
+  body: string
+): HerdrNotificationRequest => ({
+  id: `${NOTIFICATION_SOURCE}:${nextSequence()}`,
+  method: "notification.show",
+  params: {
+    body: cleanNotification(body, 240),
+    position: "top-left",
+    sound: "request",
+    title: cleanNotification(title, 80),
+  },
+});
+
 const sendToHerdr: Report = (request) => {
-  if (process.env.HERDR_ENV !== "1") return;
+  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;
+  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?.();
@@ -41,22 +84,41 @@ const sendToHerdr: Report = (request) => {
 
 export class HerdrAdvisorActivity {
   #activeConsultations = 0;
-
-  constructor(private readonly report: Report = sendToHerdr) {}
+  private readonly report: Report;
+  private readonly enabled: () => boolean;
+
+  constructor(
+    report: Report = sendToHerdr,
+    enabled: () => boolean = () => true
+  ) {
+    this.report = report;
+    this.enabled = enabled;
+  }
 
   start() {
+    if (!this.enabled()) {
+      return;
+    }
     this.#activeConsultations += 1;
-    if (this.#activeConsultations === 1) this.safeReport(false);
+    if (this.#activeConsultations === 1) {
+      this.safeReport(false);
+    }
   }
 
   finish() {
-    if (this.#activeConsultations === 0) return;
+    if (this.#activeConsultations === 0) {
+      return;
+    }
     this.#activeConsultations -= 1;
-    if (this.#activeConsultations === 0) this.safeReport(true);
+    if (this.#activeConsultations === 0) {
+      this.safeReport(true);
+    }
   }
 
   clear() {
-    if (this.#activeConsultations === 0) return;
+    if (this.#activeConsultations === 0) {
+      return;
+    }
     this.#activeConsultations = 0;
     this.safeReport(true);
   }
@@ -65,20 +127,22 @@ export class HerdrAdvisorActivity {
     try {
       this.report(this.request(clear));
     } catch {
-      // Herdr is optional; an unavailable integration must never affect advice.
+      /* Herdr is optional. */
     }
   }
 
-  private request(clear: boolean): HerdrRequest {
+  private request(clear: boolean): HerdrMetadataRequest {
     return {
       id: `${SOURCE}:${nextSequence()}`,
       method: "pane.report_metadata",
       params: {
-        pane_id: process.env.HERDR_PANE_ID ?? "",
-        source: SOURCE,
         agent: "pi",
         applies_to_source: HERDR_PI_SOURCE,
-        ...(clear ? { clear_state_labels: true } : { state_labels: { working: "seeking advice" } }),
+        pane_id: process.env.HERDR_PANE_ID ?? "",
+        source: SOURCE,
+        ...(clear
+          ? { clear_state_labels: true }
+          : { state_labels: { working: "seeking advice" } }),
         seq: nextSequence(),
       },
     };
@@ -87,40 +151,91 @@ export class HerdrAdvisorActivity {
 
 export class HerdrAdvisorBlock {
   #blocked = false;
-
-  constructor(private readonly report: Report = sendToHerdr) {}
+  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;
+    }
     this.#blocked = true;
     this.safeReport({ blocked: reason });
   }
 
   clear() {
-    if (!this.#blocked) return;
+    if (!this.isBlocked()) {
+      return;
+    }
     this.#blocked = false;
+    if (!this.enabled()) {
+      return;
+    }
     try {
       this.report({
         id: `${BLOCK_SOURCE}:${nextSequence()}`,
         method: "pane.report_metadata",
-        params: { pane_id: process.env.HERDR_PANE_ID ?? "", source: BLOCK_SOURCE, agent: "pi", applies_to_source: HERDR_PI_SOURCE, clear_state_labels: true, seq: nextSequence() },
+        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 remains optional.
+      /* Herdr is optional. */
     }
   }
 
+  private isBlocked() {
+    return this.#blocked;
+  }
+
   private safeReport(labels: { blocked: string }) {
     try {
       this.report({
         id: `${BLOCK_SOURCE}:${nextSequence()}`,
         method: "pane.report_metadata",
-        params: { pane_id: process.env.HERDR_PANE_ID ?? "", source: BLOCK_SOURCE, agent: "pi", applies_to_source: HERDR_PI_SOURCE, state_labels: labels, seq: nextSequence() },
+        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 remains optional.
+      /* Herdr is optional. */
     }
   }
 }
 
-export const herdrAdvisorActivity = new HerdrAdvisorActivity();
-export const herdrAdvisorBlock = new HerdrAdvisorBlock();
+export const notifyHerdrAdvisorFailure = (title: string, body: string) => {
+  if (!advisorHerdrIntegrationRef) {
+    return;
+  }
+  try {
+    sendToHerdr(createHerdrNotificationRequest(title, body));
+  } catch {
+    /* Herdr transport never changes Advisor safety. */
+  }
+};
+
+export const herdrAdvisorActivity = new HerdrAdvisorActivity(
+  sendToHerdr,
+  () => advisorHerdrIntegrationRef
+);
+export const herdrAdvisorBlock = new HerdrAdvisorBlock(
+  sendToHerdr,
+  () => advisorHerdrIntegrationRef
+);