pi-advisor-flow 0.5.5 → 0.6.0

package/src/config/validation.ts

@@ -1,72 +1,29 @@
-import { GIT_CONTEXT_LEVELS, isValidGitContextLevel } from "../git.js";
-import {
-  ADVISOR_TOOL_POLICIES,
-  type AdvisorConfig,
-  GATE_FAILURE_MODES,
-  MAX_CONTEXT_MAX_CHARS,
-} from "./types.js";
-
-const CONFIG_KEYS = new Set<keyof AdvisorConfig>([
-  "advisor",
-  "advisorAutoLoopGate",
-  "advisorBlockOnBlocked",
-  "advisorCollapseResponses",
-  "advisorCompletionGate",
-  "advisorCustomInvocation",
-  "advisorEffort",
-  "advisorFailureGate",
-  "advisorGitContext",
-  "advisorGitContextMaxChars",
-  "advisorHerdrIntegration",
-  "advisorLoopThreshold",
-  "advisorMaxCallsPerSession",
-  "advisorPlanGate",
-  "advisorSessionSummary",
-  "advisorScoutEnabled",
-  "showUsageDetails",
-  "showUsageFooter",
-  "simpleMode",
-  "alwaysOn",
-  "advisorToolResultMaxBytes",
-  "advisorToolResultMaxLines",
-  "advisorTrackedFileContent",
-  "advisorRedactSecrets",
-  "advisorUntrackedContent",
-  "advisorOutcomeLogging",
-  "advisorToolPolicies",
-  "contextMaxChars",
-  "executor",
-  "executorEffort",
-  "gateFailureMode",
-]);
-
-const BOOLEAN_CONFIG_KEYS = [
-  "advisorPlanGate",
-  "advisorFailureGate",
-  "advisorCompletionGate",
-  "advisorCollapseResponses",
-  "advisorBlockOnBlocked",
-  "advisorAutoLoopGate",
-  "advisorSessionSummary",
-  "advisorScoutEnabled",
-  "showUsageDetails",
-  "showUsageFooter",
-  "simpleMode",
-  "alwaysOn",
-  "advisorHerdrIntegration",
-  "advisorTrackedFileContent",
-  "advisorRedactSecrets",
-  "advisorUntrackedContent",
-  "advisorOutcomeLogging",
-] as const;
+import type { ConfigKeySchema } from "./schema.ts";
+import { CONFIG_SCHEMA, type ConfigKey, 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.
+export {
+  isValidAdvisorToolPolicies,
+  isValidContextMaxChars,
+  isValidGateFailureMode,
+  isValidLoopThreshold,
+  isValidMaxCallsPerSession,
+  isValidToolResultMaxBytes,
+  isValidToolResultMaxLines,
+} from "./schema.ts";
+
+const CONFIG_KEYS = new Set<ConfigKey>(
+  Object.keys(CONFIG_SCHEMA) as ConfigKey[]
+);
+
+const keysOfType = (type: ConfigKeySchema["type"]): readonly ConfigKey[] =>
+  (Object.keys(CONFIG_SCHEMA) as ConfigKey[]).filter(
+    (key) => SCHEMA_BY_KEY[key].type === type
+  );
 
-const STRING_CONFIG_KEYS = [
-  "executor",
-  "advisor",
-  "executorEffort",
-  "advisorEffort",
-  "advisorCustomInvocation",
-] as const;
+const BOOLEAN_CONFIG_KEYS = keysOfType("boolean");
+const STRING_CONFIG_KEYS = keysOfType("string");
 
 type ConfigRecord = Record<string, unknown>;
 
@@ -81,20 +38,12 @@ const invalidConfigValue = (
 };
 
 export const unknownConfigKeys = (config: ConfigRecord) =>
-  Object.keys(config).filter(
-    (key) => !CONFIG_KEYS.has(key as keyof AdvisorConfig)
-  );
+  Object.keys(config).filter((key) => !CONFIG_KEYS.has(key as ConfigKey));
 
 const validateStringValues = (config: ConfigRecord, path: string) => {
   for (const key of STRING_CONFIG_KEYS) {
     if (config[key] !== undefined && typeof config[key] !== "string") {
-      invalidConfigValue(
-        path,
-        key,
-        key === "executor" || key === "advisor"
-          ? "a provider/model string"
-          : "a string"
-      );
+      invalidConfigValue(path, key, SCHEMA_BY_KEY[key].accepted);
     }
   }
 };
@@ -102,91 +51,46 @@ 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") {
-      invalidConfigValue(path, key, "true or false");
+      invalidConfigValue(path, key, SCHEMA_BY_KEY[key].accepted);
     }
   }
 };
 
-export const isValidAdvisorToolPolicies = (
-  value: unknown
-): value is Record<string, (typeof ADVISOR_TOOL_POLICIES)[number]> => {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return false;
+const validateNumericValues = (config: ConfigRecord, path: string) => {
+  for (const key of keysOfType("number")) {
+    const isValid = SCHEMA_BY_KEY[key].validate;
+    if (
+      config[key] !== undefined &&
+      isValid !== undefined &&
+      !isValid(config[key])
+    ) {
+      invalidConfigValue(path, key, SCHEMA_BY_KEY[key].accepted);
+    }
   }
-  return Object.entries(value).every(
-    ([toolName, policy]) =>
-      toolName.trim().length > 0 &&
-      typeof policy === "string" &&
-      ADVISOR_TOOL_POLICIES.includes(
-        policy as (typeof ADVISOR_TOOL_POLICIES)[number]
-      )
-  );
 };
 
-export const isValidContextMaxChars = (value: unknown): value is number =>
-  typeof value === "number" &&
-  Number.isSafeInteger(value) &&
-  value >= 0 &&
-  value <= MAX_CONTEXT_MAX_CHARS;
-
-export const isValidLoopThreshold = (value: unknown): value is number =>
-  typeof value === "number" && Number.isSafeInteger(value) && value >= 2;
-
-export const isValidMaxCallsPerSession = (value: unknown): value is number =>
-  typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-
-export const isValidGateFailureMode = (
-  value: unknown
-): value is (typeof GATE_FAILURE_MODES)[number] =>
-  typeof value === "string" &&
-  GATE_FAILURE_MODES.includes(value as (typeof GATE_FAILURE_MODES)[number]);
-
-export const isValidToolResultMaxLines = (value: unknown): value is number =>
-  typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-
-export const isValidToolResultMaxBytes = (value: unknown): value is number =>
-  typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const validateEnumValues = (config: ConfigRecord, path: string) => {
+  for (const key of keysOfType("enum")) {
+    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 validateNumericValues = (config: ConfigRecord, path: string) => {
-  const numericRules: [
-    keyof AdvisorConfig,
-    (value: unknown) => boolean,
-    string,
-  ][] = [
-    [
-      "contextMaxChars",
-      isValidContextMaxChars,
-      `a safe integer from 0 through ${MAX_CONTEXT_MAX_CHARS}`,
-    ],
-    [
-      "advisorLoopThreshold",
-      isValidLoopThreshold,
-      "a safe integer of at least 2",
-    ],
-    [
-      "advisorMaxCallsPerSession",
-      isValidMaxCallsPerSession,
-      "a non-negative safe integer",
-    ],
-    [
-      "advisorToolResultMaxLines",
-      isValidToolResultMaxLines,
-      "a non-negative safe integer",
-    ],
-    [
-      "advisorToolResultMaxBytes",
-      isValidToolResultMaxBytes,
-      "a non-negative safe integer",
-    ],
-    [
-      "advisorGitContextMaxChars",
-      isValidToolResultMaxBytes,
-      "a non-negative safe integer",
-    ],
-  ];
-  for (const [key, isValid, description] of numericRules) {
-    if (config[key] !== undefined && !isValid(config[key])) {
-      invalidConfigValue(path, key, description);
+const validateObjectValues = (config: ConfigRecord, path: string) => {
+  for (const key of keysOfType("object")) {
+    const isValid = SCHEMA_BY_KEY[key].validate;
+    if (
+      config[key] !== undefined &&
+      isValid !== undefined &&
+      !isValid(config[key])
+    ) {
+      invalidConfigValue(path, key, SCHEMA_BY_KEY[key].accepted);
     }
   }
 };
@@ -204,31 +108,7 @@ export const validateConfig = (
   validateStringValues(config, path);
   validateBooleanValues(config, path);
   validateNumericValues(config, path);
-  if (
-    config.advisorToolPolicies !== undefined &&
-    !isValidAdvisorToolPolicies(config.advisorToolPolicies)
-  ) {
-    invalidConfigValue(
-      path,
-      "advisorToolPolicies",
-      "a JSON object with non-empty tool names and full, summary, or exclude values"
-    );
-  }
-  if (
-    config.gateFailureMode !== undefined &&
-    !isValidGateFailureMode(config.gateFailureMode)
-  ) {
-    invalidConfigValue(path, "gateFailureMode", GATE_FAILURE_MODES.join(", "));
-  }
-  if (
-    config.advisorGitContext !== undefined &&
-    !isValidGitContextLevel(config.advisorGitContext)
-  ) {
-    invalidConfigValue(
-      path,
-      "advisorGitContext",
-      GIT_CONTEXT_LEVELS.join(", ")
-    );
-  }
+  validateObjectValues(config, path);
+  validateEnumValues(config, path);
   return true;
 };

package/src/config.ts

@@ -1,5 +1,5 @@
 // biome-ignore lint/performance/noBarrelFile: this facade intentionally preserves the public config module contract.
-export { parseArgs } from "./config/args.js";
+export { parseArgs } from "./config/args.ts";
 export {
   advisorAutoLoopGateRef,
   advisorBlockOnBlockedRef,
@@ -68,21 +68,21 @@ export {
   showUsageFooterRef,
   simpleModeRef,
   splitRef,
-} from "./config/state.js";
-export type { SaveConfigOptions } from "./config/storage.js";
+} from "./config/state.ts";
+export type { SaveConfigOptions } from "./config/storage.ts";
 export {
   configPaths,
   loadConfig,
   resetConfigCache,
   saveConfig,
   saveGlobalOutcomeLogging,
-} from "./config/storage.js";
+} from "./config/storage.ts";
 export type {
   AdvisorConfig,
   AdvisorToolPolicies,
   AdvisorToolPolicy,
   GateFailureMode,
-} from "./config/types.js";
+} from "./config/types.ts";
 export {
   ADVISOR_TOOL_POLICIES,
   DEFAULT_ADVISOR_GIT_CONTEXT_MAX_CHARS,
@@ -91,7 +91,7 @@ export {
   DEFAULT_CONTEXT_MAX_CHARS,
   GATE_FAILURE_MODES,
   MAX_CONTEXT_MAX_CHARS,
-} from "./config/types.js";
+} from "./config/types.ts";
 export {
   isValidAdvisorToolPolicies,
   isValidContextMaxChars,
@@ -101,4 +101,4 @@ export {
   isValidToolResultMaxBytes,
   isValidToolResultMaxLines,
   validateConfig,
-} from "./config/validation.js";
+} from "./config/validation.ts";

package/src/content-utils.ts

@@ -0,0 +1,30 @@
+/** Shared untyped-content inspection helpers. */
+
+export type RecordValue = Record<string, unknown>;
+
+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 contentParts = (content: unknown): unknown[] => {
+  if (typeof content === "string") {
+    return [content];
+  }
+  return Array.isArray(content) ? content : [];
+};
+
+/** Longest UTF-8 prefix of `value` within `maxBytes`, in linear time. */
+export const capUtf8Bytes = (value: string, maxBytes: number): string => {
+  let result = "";
+  let used = 0;
+  for (const character of value) {
+    const characterBytes = byteLength(character);
+    if (used + characterBytes > maxBytes) {
+      break;
+    }
+    result += character;
+    used += characterBytes;
+  }
+  return result;
+};

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;