pi-advisor-flow 0.5.6 → 0.7.0

package/src/conversation.ts

@@ -4,24 +4,11 @@ import {
   advisorToolPoliciesRef,
   advisorToolResultMaxBytesRef,
   advisorToolResultMaxLinesRef,
-} from "./config/state.js";
-import type { AdvisorToolPolicies } from "./config/types.js";
-import {
-  DEFAULT_ADVISOR_TOOL_RESULT_MAX_BYTES,
-  DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES,
-} from "./config/types.js";
-
-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 : [];
-};
+} from "./config/state.ts";
+import type { AdvisorToolPolicies } from "./config/types.ts";
+import { contentParts, isRecord, 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") {
@@ -36,153 +23,6 @@ const textFromPart = (part: unknown): string => {
 export const textFrom = (content: unknown): string =>
   contentParts(content).map(textFromPart).join("\n").trim();
 
-const byteLength = (value: string) => Buffer.byteLength(value, "utf8");
-
-const REDACTION_MARKER = "[REDACTED SECRET]";
-const PEM_BEGIN_PATTERN = /-----BEGIN(?: [A-Z0-9]+)? PRIVATE KEY-----/gi;
-const PEM_END_PATTERN = /-----END(?: [A-Z0-9]+)? PRIVATE KEY-----/i;
-const SECRET_PATTERNS = [
-  /-----BEGIN(?: [A-Z0-9]+)? PRIVATE KEY-----[\s\S]*?-----END(?: [A-Z0-9]+)? PRIVATE KEY-----/gi,
-  /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi,
-  /\b(?:api[_-]?key|token|secret|password|passwd)\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s"'&,;)}\]]+)/gi,
-  /([a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/gi,
-  /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g,
-  /\b(?:aws_secret_access_key|aws_session_token)\s*[:=]\s*[^\s"'&,;)}\]]+/gi,
-] as const;
-
-const redactUnterminatedPem = (value: string): string => {
-  const begins = [...value.matchAll(PEM_BEGIN_PATTERN)];
-  const lastBegin = begins.at(-1);
-  if (lastBegin?.index === undefined) {
-    return value;
-  }
-  const hasEnd = PEM_END_PATTERN.test(
-    value.slice(lastBegin.index + lastBegin[0].length)
-  );
-  return hasEnd
-    ? value
-    : `${value.slice(0, lastBegin.index)}${REDACTION_MARKER}`;
-};
-
-/** Redacts common credential forms locally; it is not a data-classification system. */
-export const redactSecrets = (value: string): string => {
-  let redacted = redactUnterminatedPem(value);
-  for (const pattern of SECRET_PATTERNS) {
-    redacted = redacted.replace(pattern, (_match, scheme) =>
-      typeof scheme === "string"
-        ? `${scheme}${REDACTION_MARKER}@`
-        : REDACTION_MARKER
-    );
-  }
-  return redacted;
-};
-
-/** Redacts before a byte-safe cap so no secret fragment survives truncation. */
-export const redactAndCapText = (
-  value: string,
-  maxBytes: number,
-  redact = true
-): string => {
-  const source = redact ? redactSecrets(value) : value;
-  let result = "";
-  for (const character of source) {
-    if (byteLength(result + character) > maxBytes) {
-      break;
-    }
-    result += character;
-  }
-  return result;
-};
-
-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 markerBytes = byteLength(marker);
-  if (maxBytes < markerBytes || maxLines === 1) {
-    const content = [...marker].reduce(
-      (result, character) =>
-        byteLength(result + character) <= maxBytes
-          ? result + character
-          : result,
-      ""
-    );
-    return {
-      content,
-      omittedLines: totalLines,
-      totalBytes,
-      totalLines,
-      truncated: true,
-    };
-  }
-  const headCount = Math.floor((maxLines - 1) / 2);
-  const tailCount = maxLines - 1 - headCount;
-  const collect = (
-    candidates: string[],
-    maxEntries: number,
-    maxContentBytes: number
-  ) => {
-    const selected: string[] = [];
-    let used = 0;
-    for (const line of candidates.slice(0, maxEntries)) {
-      const next = used + byteLength(line) + (selected.length ? 1 : 0);
-      if (next > maxContentBytes) {
-        break;
-      }
-      selected.push(line);
-      used = next;
-    }
-    return selected;
-  };
-  const availableBytes = maxBytes - markerBytes - 2;
-  const head = collect(lines, headCount, Math.floor(availableBytes / 2));
-  const tail = collect(
-    lines.slice(Math.max(head.length, lines.length - tailCount)),
-    tailCount,
-    availableBytes - byteLength(head.join("\n"))
-  );
-  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,
   policies: AdvisorToolPolicies,
@@ -284,6 +124,9 @@ export const conversationEntry = (
   }
 };
 
+const omissionMarker = (omitted: number) =>
+  `[Older context omitted: ${omitted} complete entr${omitted === 1 ? "y" : "ies"}]`;
+
 const selectRecentEntries = (entries: string[], maxChars: number): string => {
   const separator = "\n\n";
   const joined = entries.join(separator);
@@ -304,19 +147,21 @@ const selectRecentEntries = (entries: string[], maxChars: number): string => {
     const entry = entries[index];
     const candidateCount = selected.length + 1;
     const omitted = entries.length - candidateCount;
-    const marker = `[Older context omitted: ${omitted} complete entr${omitted === 1 ? "y" : "ies"}]`;
     const candidateLength =
       selectedLength +
       entry.length +
       (selected.length > 0 ? separator.length : 0);
-    if (marker.length + separator.length + candidateLength > maxChars) {
+    if (
+      omissionMarker(omitted).length + separator.length + candidateLength >
+      maxChars
+    ) {
       break;
     }
     selected.unshift(entry);
     selectedLength = candidateLength;
   }
   const omitted = entries.length - Math.max(1, selected.length);
-  const marker = `[Older context omitted: ${omitted} complete entr${omitted === 1 ? "y" : "ies"}]`;
+  const marker = omissionMarker(omitted);
   if (selected.length > 0) {
     return `${marker}${separator}${selected.join(separator)}`;
   }

package/src/git.ts

@@ -16,17 +16,14 @@ const LEVEL_RANK: Record<GitContextLevel, number> = {
   summary: 1,
 };
 
-/**
- * The Executor may request no more repository context than the user configured.
- * A model cannot widen its own disclosure allowance.
- */
+/** The Executor may narrow but never widen the user's disclosure allowance. */
 export const clampGitContextLevel = (
   requested: GitContextLevel,
   allowed: GitContextLevel
 ): GitContextLevel =>
   LEVEL_RANK[requested] <= LEVEL_RANK[allowed] ? requested : allowed;
 
-export type GitContextStatus =
+type GitContextStatus =
   | "disabled"
   | "no-changes"
   | "collected"
@@ -77,11 +74,7 @@ const GIT_MAX_BUFFER = 16 * 1024 * 1024;
 
 export type GitRunner = (args: string[], cwd: string) => string;
 
-/**
- * Collection runs several git commands. A per-command timeout alone would let a
- * pathological repository block for the sum of them, so the budget is shared:
- * each command may use only the time remaining before the overall deadline.
- */
+/** Shares one deadline across commands so a pathological repository cannot block for the sum of per-command timeouts. */
 const deadlineRunner = (): GitRunner => {
   const expiresAt = Date.now() + GIT_TOTAL_TIMEOUT_MS;
   return (args, cwd) => {
@@ -112,14 +105,7 @@ const diffBase = (run: GitRunner, cwd: string): string => {
   }
 };
 
-/**
- * Collects working-tree changes relative to HEAD, covering staged and unstaged
- * work. Untracked files are reported by name only and never by content.
- *
- * `summary` discloses file names, change status, and line counts. It must not
- * include diff hunk headers: git derives those from surrounding file content,
- * so they can reproduce a secret from a line the change never touched.
- */
+/** Collects staged and unstaged changes vs HEAD; summary omits diff hunk headers because git derives them from untouched lines that can reproduce secrets. */
 export const collectGitContext = (
   cwd: string,
   level: GitContextLevel,

package/src/herdr.ts

@@ -1,9 +1,9 @@
 import net from "node:net";
-import { getAdvisorSettings } from "./config/state.js";
-import { redactSecrets } from "./conversation.js";
+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 HERDR_NOTIFICATION_METHOD = "notification.show";
 
 const SOURCE = "pi-advisor:advisor-activity";
 const BLOCK_SOURCE = "pi-advisor:advisor-block";
@@ -38,13 +38,11 @@ export interface HerdrNotificationRequest {
     sound: "request";
   };
 }
-export type HerdrRequest = HerdrMetadataRequest | HerdrNotificationRequest;
+type HerdrRequest = HerdrMetadataRequest | HerdrNotificationRequest;
 type Report = (request: HerdrRequest) => void;
 
-// Herdr only accepts semantic state from the pane's lifecycle authority, which
-// for pi is herdr's own herdr-agent-state extension (source "herdr:pi"). Socket
-// reports from any other source are dropped, so the blocked state has to be
-// signalled through the in-process pi event bus that integration listens on.
+// 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;
 

package/src/jev/client.ts

@@ -0,0 +1,348 @@
+import type { EntryType, Fetch, Questions } from "@typesafe-ai/sdk";
+import {
+  advisorJevModelRef,
+  advisorJevPricePerMtokRef,
+  advisorJevTimeoutMsRef,
+} from "../config/state.ts";
+import { redactSecrets } from "../redaction.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 interface JevUsage {
+  cost: number;
+  inputTokens: number;
+  outputTokens: number;
+}
+
+export interface JevAskResult {
+  answers: Record<string, unknown>;
+  model: string;
+  usage: JevUsage;
+}
+
+export interface JevClientOptions {
+  apiKey: string;
+  fetch?: Fetch;
+  model: string;
+  pricePerMtok?: number;
+  timeoutMs: number;
+  transport: JevTransportKind;
+}
+
+const ENDPOINTS: Record<JevTransportKind, string> = {
+  openrouter: "https://openrouter.ai/api/alpha/decisions",
+  typesafe: "https://api.typesafe.ai/v1/systemone",
+};
+
+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 errorDetail = (error: unknown): string => {
+  if (typeof error === "string") {
+    return error;
+  }
+  if (error && typeof error === "object" && "message" in error) {
+    return String((error as { message: unknown }).message);
+  }
+  return "";
+};
+
+const statusCategory = (status: number): JevErrorCategory => {
+  if (status === 401 || status === 403) {
+    return "auth";
+  }
+  if (status === 400 || status === 422) {
+    return "malformed";
+  }
+  return "error";
+};
+
+const openRouterModelId = (model: string) =>
+  model.includes("/") ? model : `~typesafe/${model}`;
+
+interface AttemptOutcome {
+  answers?: Record<string, unknown>;
+  failure?: JevFailure;
+  model?: string;
+  retryable?: boolean;
+  usage?: { input_tokens?: unknown; output_tokens?: unknown };
+}
+
+/** 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. */
+export class JevClient {
+  readonly #apiKey: string;
+  readonly #endpoint: string;
+  readonly #fetch: Fetch;
+  readonly #model: string;
+  readonly #pricePerMtok: number | undefined;
+  readonly #timeoutMs: number;
+
+  constructor({
+    apiKey,
+    fetch,
+    model,
+    pricePerMtok,
+    timeoutMs,
+    transport,
+  }: JevClientOptions) {
+    this.#apiKey = apiKey;
+    this.#endpoint = ENDPOINTS[transport];
+    this.#fetch = fetch ?? (globalThis.fetch.bind(globalThis) as Fetch);
+    this.#model = transport === "openrouter" ? openRouterModelId(model) : model;
+    this.#pricePerMtok = pricePerMtok;
+    this.#timeoutMs = timeoutMs;
+  }
+
+  async ask(
+    state: EntryType,
+    questions: Questions,
+    signal?: AbortSignal
+  ): Promise<JevAskResult> {
+    const deadline = new AbortController();
+    const abortFromCaller = () => deadline.abort(signal?.reason);
+    signal?.addEventListener("abort", abortFromCaller, { once: true });
+    if (signal?.aborted) {
+      abortFromCaller();
+    }
+    let deadlineHit = false;
+    const timer = setTimeout(() => {
+      deadlineHit = true;
+      deadline.abort(new Error("Jev wall-time budget elapsed"));
+    }, this.#timeoutMs);
+    timer.unref?.();
+    const body = JSON.stringify({
+      model: this.#model,
+      questions,
+      state,
+    });
+    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.
+        outcome = await this.#attempt(body, deadline.signal);
+        if (!outcome.retryable || attempt >= MAX_ATTEMPTS) {
+          break;
+        }
+        await this.#backoff(deadline.signal);
+        if (deadline.signal.aborted) {
+          break;
+        }
+      }
+      return this.#settle(outcome, deadlineHit, signal);
+    } catch (error) {
+      if (signal?.aborted && !deadlineHit) {
+        throw error;
+      }
+      if (error instanceof JevFailure) {
+        throw error;
+      }
+      const message = redactSecrets(
+        error instanceof Error ? error.message : String(error)
+      );
+      throw deadlineHit
+        ? new JevFailure(
+            "timeout",
+            `Jev call exceeded its ${this.#timeoutMs} ms wall-time budget.`
+          )
+        : new JevFailure("error", message);
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abortFromCaller);
+    }
+  }
+
+  #settle(
+    outcome: AttemptOutcome,
+    deadlineHit: boolean,
+    signal: AbortSignal | undefined
+  ): JevAskResult {
+    if (outcome.answers) {
+      return this.#result(outcome);
+    }
+    if (deadlineHit && outcome.failure?.category !== "auth") {
+      throw new JevFailure(
+        "timeout",
+        `Jev call exceeded its ${this.#timeoutMs} ms wall-time budget.`
+      );
+    }
+    if (outcome.failure) {
+      throw outcome.failure;
+    }
+    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 });
+    });
+  }
+
+  async #attempt(body: string, signal: AbortSignal): Promise<AttemptOutcome> {
+    if (signal.aborted) {
+      return { retryable: false };
+    }
+    let response: Response;
+    try {
+      response = await this.#fetch(this.#endpoint, {
+        body,
+        headers: {
+          authorization: `Bearer ${this.#apiKey}`,
+          "content-type": "application/json",
+        },
+        method: "POST",
+        signal,
+      });
+    } catch (error) {
+      if (signal.aborted) {
+        return { retryable: false };
+      }
+      return {
+        retryable: true,
+        ...this.#connectionFailure(error),
+      };
+    }
+    if (response.ok) {
+      return this.#parseSuccess(response);
+    }
+    const failure = await this.#failureFromStatus(response);
+    return {
+      failure,
+      retryable: RETRYABLE_STATUSES.has(response.status),
+    };
+  }
+
+  #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> {
+    let detail = "";
+    try {
+      const parsed: unknown = await response.json();
+      const error = (parsed as { error?: unknown } | null)?.error;
+      detail = errorDetail(error);
+    } catch {
+      detail = "";
+    }
+    const message = redactSecrets(
+      `Jev ${this.#transportLabel()} request failed with HTTP ${response.status}${detail ? `: ${detail}` : ""}.`
+    );
+    return new JevFailure(statusCategory(response.status), message);
+  }
+
+  #transportLabel(): string {
+    return this.#endpoint === ENDPOINTS.openrouter ? "OpenRouter" : "TypeSafe";
+  }
+
+  async #parseSuccess(response: Response): Promise<AttemptOutcome> {
+    let parsed: unknown;
+    try {
+      parsed = await response.json();
+    } catch (error) {
+      return {
+        failure: new JevFailure(
+          "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"
+    ) {
+      return {
+        failure: new JevFailure(
+          "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"],
+    };
+  }
+
+  #result(outcome: AttemptOutcome): JevAskResult {
+    const usage = outcome.usage as
+      | { input_tokens?: unknown; output_tokens?: unknown }
+      | undefined;
+    const inputTokens = finiteTokens(usage?.input_tokens);
+    const outputTokens = finiteTokens(usage?.output_tokens);
+    const price = this.#pricePerMtok ?? advisorJevPricePerMtokRef;
+    return {
+      answers: outcome.answers ?? {},
+      model: outcome.model ?? this.#model,
+      usage: {
+        cost: (inputTokens / 1_000_000) * price,
+        inputTokens,
+        outputTokens,
+      },
+    };
+  }
+}
+
+/** A client wired from resolved credentials; reads the live Jev settings per call. */
+export const jevClientFromCredentials = (
+  credentials: JevCredentials,
+  fetch?: Fetch
+): JevClient =>
+  new JevClient({
+    apiKey: credentials.apiKey,
+    fetch,
+    model: advisorJevModelRef,
+    timeoutMs: advisorJevTimeoutMsRef,
+    transport: credentials.transport,
+  });