pi-advisor-flow 0.7.0 → 0.8.0

package/src/herdr.ts

@@ -1,108 +1,37 @@
-import net from "node:net";
 import { getAdvisorSettings } from "./config/state.ts";
-import { redactSecrets } from "./redaction.ts";
-
-// Keep the JSON-RPC method components separate from Socket's URL-string heuristic.
-const HERDR_NOTIFICATION_METHOD = "notification.show";
-
-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() * 1000;
-const nextSequence = () => {
-  sequence += 1;
-  return sequence;
-};
-
-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";
-  };
-}
-type HerdrRequest = HerdrMetadataRequest | HerdrNotificationRequest;
-type Report = (request: HerdrRequest) => void;
-
-// 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;
-};
-
-const safeEmitBlocked = (active: boolean, label = "Advisor blocked") => {
-  try {
-    emitBlocked?.(active, label);
-  } catch {
-    /* Herdr is optional. */
-  }
-};
-
-const isControlCharacter = (character: string) =>
-  character <= "\u001f" || character === "\u007f";
-
-const cleanNotification = (value: string, max: number) =>
-  [...redactSecrets(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: HERDR_NOTIFICATION_METHOD,
+import { HerdrAdvisorBlock } from "./herdr-block.ts";
+import type { HerdrMetadataRequest, Report } from "./herdr-shared.ts";
+import {
+  createHerdrNotificationRequest,
+  HERDR_PI_SOURCE,
+  nextSequence,
+  sendToHerdr,
+  SOURCE,
+} from "./herdr-shared.ts";
+
+export { HerdrAdvisorBlock } from "./herdr-block.ts";
+export {
+  createHerdrNotificationRequest,
+  type HerdrMetadataRequest,
+  type HerdrNotificationRequest,
+  setHerdrBlockedEmitter,
+} from "./herdr-shared.ts";
+
+const metadataRequest = (clear: boolean): HerdrMetadataRequest => ({
+  id: `${SOURCE}:${nextSequence()}`,
+  method: "pane.report_metadata",
   params: {
-    body: cleanNotification(body, 240),
-    position: "top-left",
-    sound: "request",
-    title: cleanNotification(title, 80),
+    agent: "pi",
+    applies_to_source: HERDR_PI_SOURCE,
+    pane_id: process.env.HERDR_PANE_ID ?? "",
+    source: SOURCE,
+    ...(clear
+      ? { clear_state_labels: true }
+      : { state_labels: { working: "seeking advice" } }),
+    seq: nextSequence(),
   },
 });
 
-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 class HerdrAdvisorActivity {
   #activeConsultations = 0;
   private readonly report: Report;
@@ -146,98 +75,7 @@ export class HerdrAdvisorActivity {
 
   private safeReport(clear: boolean) {
     try {
-      this.report(this.request(clear));
-    } catch {
-      /* Herdr is optional. */
-    }
-  }
-
-  private request(clear: boolean): HerdrMetadataRequest {
-    return {
-      id: `${SOURCE}:${nextSequence()}`,
-      method: "pane.report_metadata",
-      params: {
-        agent: "pi",
-        applies_to_source: HERDR_PI_SOURCE,
-        pane_id: process.env.HERDR_PANE_ID ?? "",
-        source: SOURCE,
-        ...(clear
-          ? { clear_state_labels: true }
-          : { state_labels: { working: "seeking advice" } }),
-        seq: nextSequence(),
-      },
-    };
-  }
-}
-
-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,
-        },
-      });
+      this.report(metadataRequest(clear));
     } catch {
       /* Herdr is optional. */
     }

package/src/jev/client.ts

@@ -1,29 +1,19 @@
 import type { EntryType, Fetch, Questions } from "@typesafe-ai/sdk";
+
 import {
   advisorJevModelRef,
   advisorJevPricePerMtokRef,
   advisorJevTimeoutMsRef,
 } from "../config/state.ts";
+import { isNumber, isRecord, isRecordOf, isString } from "../content-utils.ts";
+import type { JsonValue, RecordValue } from "../content-utils.ts";
 import { redactSecrets } from "../redaction.ts";
+import { JevFailureError } from "./failure.ts";
+import type { JevErrorCategory } from "./failure.ts";
 import type { JevCredentials, JevTransportKind } from "./transport.ts";
 
-export type JevErrorCategory =
-  | "auth"
-  | "timeout"
-  | "network"
-  | "malformed"
-  | "error";
-
-/** A classified, redacted Jev failure; never carries key material. */
-export class JevFailure extends Error {
-  readonly category: JevErrorCategory;
-
-  constructor(category: JevErrorCategory, message: string) {
-    super(message);
-    this.name = "JevFailure";
-    this.category = category;
-  }
-}
+export type { JevErrorCategory } from "./failure.ts";
+export { JevFailureError as JevFailure } from "./failure.ts";
 
 export interface JevUsage {
   cost: number;
@@ -32,7 +22,7 @@ export interface JevUsage {
 }
 
 export interface JevAskResult {
-  answers: Record<string, unknown>;
+  answers: RecordValue;
   model: string;
   usage: JevUsage;
 }
@@ -51,23 +41,22 @@ const ENDPOINTS: Record<JevTransportKind, string> = {
   typesafe: "https://api.typesafe.ai/v1/systemone",
 };
 
+const range = (from: number, to: number): number[] =>
+  Array.from({ length: to - from + 1 }, (_, index) => from + index);
+
 const RETRYABLE_STATUSES = new Set([408, 429, ...range(500, 599)]);
 const RETRY_BACKOFF_MS = 250;
 const MAX_ATTEMPTS = 2;
 
-function range(from: number, to: number): number[] {
-  return Array.from({ length: to - from + 1 }, (_, index) => from + index);
-}
-
-const finiteTokens = (value: unknown): number =>
-  typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+const finiteTokens = (value: JsonValue | undefined): number =>
+  isNumber(value) && Number.isFinite(value) && value >= 0 ? value : 0;
 
-const errorDetail = (error: unknown): string => {
-  if (typeof error === "string") {
+const errorDetail = (error: JsonValue | undefined): string => {
+  if (isString(error)) {
     return error;
   }
-  if (error && typeof error === "object" && "message" in error) {
-    return String((error as { message: unknown }).message);
+  if (isRecordOf(error) && "message" in error) {
+    return String(error.message);
   }
   return "";
 };
@@ -82,17 +71,47 @@ const statusCategory = (status: number): JevErrorCategory => {
   return "error";
 };
 
+const isObjectLike = <Value>(value: Value): value is Value & object =>
+  typeof value === "object";
+
 const openRouterModelId = (model: string) =>
   model.includes("/") ? model : `~typesafe/${model}`;
 
 interface AttemptOutcome {
-  answers?: Record<string, unknown>;
-  failure?: JevFailure;
+  answers?: RecordValue;
+  failure?: JevFailureError;
   model?: string;
   retryable?: boolean;
-  usage?: { input_tokens?: unknown; output_tokens?: unknown };
+  usage?: { input_tokens?: JsonValue; output_tokens?: JsonValue };
 }
 
+const connectionFailure = <E>(error: E) => {
+  const message = redactSecrets(
+    error instanceof Error ? error.message : String(error)
+  );
+  return {
+    failure: new JevFailureError(
+      "network",
+      `Jev connection failed: ${message}`
+    ),
+  };
+};
+
+const sleepWithAbort = (signal: AbortSignal, ms: number): Promise<void> =>
+  // oxlint-disable-next-line promise/avoid-new -- unref-ed abortable retry timer cannot be expressed with async/await.
+  new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true }
+    );
+  });
+
 /** One systemone client for both transports with a total wall deadline so
  * retries can never stall a tool call; errors are classified and redacted on
  * every path. */
@@ -114,6 +133,7 @@ export class JevClient {
   }: JevClientOptions) {
     this.#apiKey = apiKey;
     this.#endpoint = ENDPOINTS[transport];
+    // SAFETY: the bound global fetch satisfies the SDK Fetch signature; binding keeps the receiver correct.
     this.#fetch = fetch ?? (globalThis.fetch.bind(globalThis) as Fetch);
     this.#model = transport === "openrouter" ? openRouterModelId(model) : model;
     this.#pricePerMtok = pricePerMtok;
@@ -145,12 +165,12 @@ export class JevClient {
     try {
       let outcome: AttemptOutcome = {};
       for (let attempt = 1; ; attempt += 1) {
-        // biome-ignore lint/performance/noAwaitInLoops: the retry loop is bounded to one backoff by the deadline controller.
+        // The retry loop is bounded to one backoff by the deadline controller.
         outcome = await this.#attempt(body, deadline.signal);
         if (!outcome.retryable || attempt >= MAX_ATTEMPTS) {
           break;
         }
-        await this.#backoff(deadline.signal);
+        await sleepWithAbort(deadline.signal, RETRY_BACKOFF_MS);
         if (deadline.signal.aborted) {
           break;
         }
@@ -160,18 +180,18 @@ export class JevClient {
       if (signal?.aborted && !deadlineHit) {
         throw error;
       }
-      if (error instanceof JevFailure) {
+      if (error instanceof JevFailureError) {
         throw error;
       }
       const message = redactSecrets(
         error instanceof Error ? error.message : String(error)
       );
       throw deadlineHit
-        ? new JevFailure(
+        ? new JevFailureError(
             "timeout",
             `Jev call exceeded its ${this.#timeoutMs} ms wall-time budget.`
           )
-        : new JevFailure("error", message);
+        : new JevFailureError("error", message);
     } finally {
       clearTimeout(timer);
       signal?.removeEventListener("abort", abortFromCaller);
@@ -187,7 +207,7 @@ export class JevClient {
       return this.#result(outcome);
     }
     if (deadlineHit && outcome.failure?.category !== "auth") {
-      throw new JevFailure(
+      throw new JevFailureError(
         "timeout",
         `Jev call exceeded its ${this.#timeoutMs} ms wall-time budget.`
       );
@@ -198,22 +218,7 @@ export class JevClient {
     if (signal?.aborted) {
       throw new Error("Jev call aborted by the caller.");
     }
-    throw new JevFailure("error", "Jev call failed.");
-  }
-
-  async #backoff(signal: AbortSignal): Promise<void> {
-    if (signal.aborted) {
-      return;
-    }
-    await new Promise<void>((resolve) => {
-      const timer = setTimeout(resolve, RETRY_BACKOFF_MS);
-      timer.unref?.();
-      const onAbort = () => {
-        clearTimeout(timer);
-        resolve();
-      };
-      signal.addEventListener("abort", onAbort, { once: true });
-    });
+    throw new JevFailureError("error", "Jev call failed.");
   }
 
   async #attempt(body: string, signal: AbortSignal): Promise<AttemptOutcome> {
@@ -237,7 +242,7 @@ export class JevClient {
       }
       return {
         retryable: true,
-        ...this.#connectionFailure(error),
+        ...connectionFailure(error),
       };
     }
     if (response.ok) {
@@ -250,20 +255,11 @@ export class JevClient {
     };
   }
 
-  #connectionFailure(error: unknown): { failure: JevFailure } {
-    const message = redactSecrets(
-      error instanceof Error ? error.message : String(error)
-    );
-    return {
-      failure: new JevFailure("network", `Jev connection failed: ${message}`),
-    };
-  }
-
-  async #failureFromStatus(response: Response): Promise<JevFailure> {
+  async #failureFromStatus(response: Response): Promise<JevFailureError> {
     let detail = "";
     try {
       const parsed: unknown = await response.json();
-      const error = (parsed as { error?: unknown } | null)?.error;
+      const error = isRecord(parsed) ? parsed.error : undefined;
       detail = errorDetail(error);
     } catch {
       detail = "";
@@ -271,7 +267,7 @@ export class JevClient {
     const message = redactSecrets(
       `Jev ${this.#transportLabel()} request failed with HTTP ${response.status}${detail ? `: ${detail}` : ""}.`
     );
-    return new JevFailure(statusCategory(response.status), message);
+    return new JevFailureError(statusCategory(response.status), message);
   }
 
   #transportLabel(): string {
@@ -284,41 +280,35 @@ export class JevClient {
       parsed = await response.json();
     } catch (error) {
       return {
-        failure: new JevFailure(
+        failure: new JevFailureError(
           "malformed",
           `Jev response was not JSON: ${redactSecrets(error instanceof Error ? error.message : String(error))}`
         ),
       };
     }
-    const record = parsed as {
-      answers?: unknown;
-      model?: unknown;
-      usage?: unknown;
-    } | null;
-    if (
-      !record ||
-      typeof record !== "object" ||
-      !record.answers ||
-      typeof record.answers !== "object"
-    ) {
+    if (!isRecord(parsed) || !parsed.answers || !isObjectLike(parsed.answers)) {
       return {
-        failure: new JevFailure(
+        failure: new JevFailureError(
           "malformed",
           "Jev response did not include an answers object."
         ),
       };
     }
     return {
-      answers: record.answers as Record<string, unknown>,
-      model: typeof record.model === "string" ? record.model : this.#model,
-      usage: record.usage as AttemptOutcome["usage"],
+      // SAFETY: the response contract guarantees an answers object; the shape is re-validated per key by consumers.
+      answers: parsed.answers as RecordValue,
+      model: isString(parsed.model) ? parsed.model : this.#model,
+      usage: isRecordOf(parsed.usage)
+        ? {
+            input_tokens: parsed.usage.input_tokens,
+            output_tokens: parsed.usage.output_tokens,
+          }
+        : undefined,
     };
   }
 
   #result(outcome: AttemptOutcome): JevAskResult {
-    const usage = outcome.usage as
-      | { input_tokens?: unknown; output_tokens?: unknown }
-      | undefined;
+    const { usage } = outcome;
     const inputTokens = finiteTokens(usage?.input_tokens);
     const outputTokens = finiteTokens(usage?.output_tokens);
     const price = this.#pricePerMtok ?? advisorJevPricePerMtokRef;

package/src/jev/failure.ts

@@ -0,0 +1,19 @@
+export type JevErrorCategory =
+  | "auth"
+  | "timeout"
+  | "network"
+  | "malformed"
+  | "error";
+
+/** A classified, redacted Jev failure; never carries key material. */
+export class JevFailureError extends Error {
+  readonly category: JevErrorCategory;
+
+  constructor(category: JevErrorCategory, message: string) {
+    super(message);
+    this.name = "JevFailureError";
+    this.category = category;
+  }
+}
+
+export { JevFailureError as JevFailure };

package/src/jev/key-store.ts

@@ -6,8 +6,12 @@ import {
   writeFileSync,
 } from "node:fs";
 import { join } from "node:path";
+
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
 import { readExistingConfig, resetConfigCache } from "../config/storage.ts";
+import { isString } from "../content-utils.ts";
+import type { RecordValue } from "../content-utils.ts";
 import { redactSecrets } from "../redaction.ts";
 
 export type JevKeySource = "bun-secrets" | "env" | "file" | "advisor-json";
@@ -29,7 +33,7 @@ export interface JevSecretEntry {
 }
 
 export interface JevSecretsLike {
-  delete: (options: JevSecretEntry) => Promise<unknown>;
+  delete: (options: JevSecretEntry) => Promise<boolean | undefined>;
   get: (options: JevSecretEntry) => Promise<string | null | undefined>;
   set: (options: JevSecretEntry & { value: string }) => Promise<void>;
 }
@@ -37,8 +41,8 @@ export interface JevSecretsLike {
 export interface JevKeyStoreDeps {
   /** Deletes the extension-managed key file; injectable for tests. */
   deleteFileStore?: () => void;
-  env?: Record<string, string | undefined>;
-  readAdvisorJson?: () => Record<string, unknown>;
+  env?: NodeJS.ProcessEnv;
+  readAdvisorJson?: () => RecordValue;
   /** Reads the extension-managed 0600 key file; injectable for tests. */
   readFileStore?: () => string | undefined;
   /** Inject `null` to simulate a runtime without a secret store. */
@@ -55,8 +59,15 @@ const KEY_FILE_MODE = 0o600;
 
 const keyFilePath = () => join(getAgentDir(), "typesafe_api_key");
 
-const runtimeSecrets = (): JevSecretsLike | undefined =>
-  (globalThis as { Bun?: { secrets?: JevSecretsLike } }).Bun?.secrets;
+interface BunGlobal {
+  Bun?: { secrets?: JevSecretsLike };
+}
+
+const runtimeSecrets = (): JevSecretsLike | undefined => {
+  // SAFETY: only Bun runtimes expose Bun.secrets on globalThis; others leave it undefined.
+  const bun = globalThis as BunGlobal;
+  return bun.Bun?.secrets;
+};
 
 /** Whether the current runtime offers a Bun.secrets store. */
 export const hasRuntimeSecretStore = () => runtimeSecrets() !== undefined;
@@ -64,12 +75,12 @@ export const hasRuntimeSecretStore = () => runtimeSecrets() !== undefined;
 const normalizeKey = (value: string | null | undefined): string | undefined =>
   value?.trim() || undefined;
 
-const readAdvisorJsonConfig = (): Record<string, unknown> =>
+const readAdvisorJsonConfig = (): RecordValue =>
   readExistingConfig(join(getAgentDir(), "advisor.json"));
 
 const defaultReadFileStore = (): string | undefined => {
   try {
-    return normalizeKey(readFileSync(keyFilePath(), "utf8"));
+    return normalizeKey(readFileSync(keyFilePath(), "utf-8"));
   } catch {
     return undefined;
   }
@@ -86,7 +97,7 @@ const defaultDeleteFileStore = () => {
   rmSync(keyFilePath(), { force: true });
 };
 
-const messageOf = (error: unknown) =>
+const messageOf = <E>(error: E) =>
   redactSecrets(error instanceof Error ? error.message : String(error));
 
 /** Resolves the TypeSafe API key: Bun.secrets → env var → the extension's
@@ -123,7 +134,7 @@ export const resolveTypeSafeKey = async (
   }
   const config = (deps.readAdvisorJson ?? readAdvisorJsonConfig)();
   const staged = config[TYPESAFE_KEY_CONFIG_FIELD];
-  if (typeof staged === "string") {
+  if (isString(staged)) {
     const fromConfig = normalizeKey(staged);
     if (fromConfig) {
       return { key: fromConfig, source: "advisor-json" };
@@ -223,8 +234,12 @@ export const removeTypeSafeKeyFromAdvisorJson = (): JevKeyStoreResult => {
     if (!(TYPESAFE_KEY_CONFIG_FIELD in existing)) {
       return { message: "No plaintext key in advisor.json.", ok: true };
     }
-    delete existing[TYPESAFE_KEY_CONFIG_FIELD];
-    writeFileSync(path, `${JSON.stringify(existing, null, 2)}\n`);
+    const retained = Object.fromEntries(
+      Object.entries(existing).filter(
+        ([key]) => key !== TYPESAFE_KEY_CONFIG_FIELD
+      )
+    );
+    writeFileSync(path, `${JSON.stringify(retained, null, 2)}\n`);
     resetConfigCache();
     return { message: "Plaintext key removed from advisor.json.", ok: true };
   } catch (error) {