pi-advisor-flow 0.5.0 → 0.5.2

package/src/config/types.ts

@@ -0,0 +1,63 @@
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+} from "@earendil-works/pi-coding-agent";
+import type { GitContextLevel } from "../git.js";
+
+export const DEFAULT_CONTEXT_MAX_CHARS = 15_000;
+export const MAX_CONTEXT_MAX_CHARS = Number.MAX_SAFE_INTEGER;
+export const DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES = DEFAULT_MAX_LINES;
+export const DEFAULT_ADVISOR_TOOL_RESULT_MAX_BYTES = DEFAULT_MAX_BYTES;
+export const DEFAULT_ADVISOR_GIT_CONTEXT_MAX_CHARS = 20_000;
+
+export type AdvisorToolPolicy = "full" | "summary" | "exclude";
+export type AdvisorToolPolicies = Record<string, AdvisorToolPolicy>;
+export const ADVISOR_TOOL_POLICIES: AdvisorToolPolicy[] = [
+  "full",
+  "summary",
+  "exclude",
+];
+
+export type GateFailureMode =
+  | "block-session"
+  | "block-tool"
+  | "warn-and-continue";
+export const GATE_FAILURE_MODES: GateFailureMode[] = [
+  "block-session",
+  "block-tool",
+  "warn-and-continue",
+];
+
+export interface AdvisorConfig {
+  advisor?: string;
+  advisorAutoLoopGate?: boolean;
+  advisorBlockOnBlocked?: boolean;
+  advisorCollapseResponses?: boolean;
+  advisorCompletionGate?: boolean;
+  advisorCustomInvocation?: string;
+  advisorEffort?: string;
+  advisorFailureGate?: boolean;
+  advisorGitContext?: GitContextLevel;
+  advisorGitContextMaxChars?: number;
+  advisorHerdrIntegration?: boolean;
+  advisorLoopThreshold?: number;
+  advisorMaxCallsPerSession?: number;
+  advisorOutcomeLogging?: boolean;
+  advisorPlanGate?: boolean;
+  advisorRedactSecrets?: boolean;
+  advisorScoutEnabled?: boolean;
+  advisorSessionSummary?: boolean;
+  advisorToolPolicies?: AdvisorToolPolicies;
+  advisorToolResultMaxBytes?: number;
+  advisorToolResultMaxLines?: number;
+  advisorTrackedFileContent?: boolean;
+  advisorUntrackedContent?: boolean;
+  alwaysOn?: boolean;
+  contextMaxChars?: number;
+  executor?: string;
+  executorEffort?: string;
+  gateFailureMode?: GateFailureMode;
+  showUsageDetails?: boolean;
+  showUsageFooter?: boolean;
+  simpleMode?: boolean;
+}

package/src/config/validation.ts

@@ -0,0 +1,234 @@
+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;
+
+const STRING_CONFIG_KEYS = [
+  "executor",
+  "advisor",
+  "executorEffort",
+  "advisorEffort",
+  "advisorCustomInvocation",
+] as const;
+
+type ConfigRecord = Record<string, unknown>;
+
+const invalidConfigValue = (
+  path: string,
+  key: string,
+  accepted: string
+): never => {
+  throw new TypeError(
+    `Invalid advisor configuration at ${path}, key ${JSON.stringify(key)}: expected ${accepted}.`
+  );
+};
+
+export const unknownConfigKeys = (config: ConfigRecord) =>
+  Object.keys(config).filter(
+    (key) => !CONFIG_KEYS.has(key as keyof AdvisorConfig)
+  );
+
+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"
+      );
+    }
+  }
+};
+
+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");
+    }
+  }
+};
+
+export const isValidAdvisorToolPolicies = (
+  value: unknown
+): value is Record<string, (typeof ADVISOR_TOOL_POLICIES)[number]> => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  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 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);
+    }
+  }
+};
+
+export const validateConfig = (
+  value: unknown,
+  path = "advisor.json"
+): value is AdvisorConfig => {
+  if (!value || typeof value !== "object" || Array.isArray(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);
+  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(", ")
+    );
+  }
+  return true;
+};