pi-advisor-flow 0.5.5 → 0.6.0

package/src/config/schema.ts

@@ -0,0 +1,322 @@
+import { GIT_CONTEXT_LEVELS, isValidGitContextLevel } from "../git.ts";
+import {
+  advisorAutoLoopGateRef,
+  advisorBlockOnBlockedRef,
+  advisorCollapseResponsesRef,
+  advisorCompletionGateRef,
+  advisorCustomInvocationRef,
+  advisorEffortRef,
+  advisorFailureGateRef,
+  advisorFailureModeRef,
+  advisorGitContextMaxCharsRef,
+  advisorGitContextRef,
+  advisorHerdrIntegrationRef,
+  advisorLoopThresholdRef,
+  advisorMaxCallsPerSessionRef,
+  advisorOutcomeLoggingRef,
+  advisorPlanGateRef,
+  advisorRedactSecretsRef,
+  advisorRef,
+  advisorScoutEnabledRef,
+  advisorSessionSummaryRef,
+  advisorToolPoliciesRef,
+  advisorToolResultMaxBytesRef,
+  advisorToolResultMaxLinesRef,
+  advisorTrackedFileContentRef,
+  advisorUntrackedContentRef,
+  alwaysOnRef,
+  contextMaxCharsRef,
+  executorEffortRef,
+  executorRef,
+  showUsageDetailsRef,
+  showUsageFooterRef,
+  simpleModeRef,
+} from "./state.ts";
+import {
+  ADVISOR_TOOL_POLICIES,
+  type AdvisorConfig,
+  GATE_FAILURE_MODES,
+  MAX_CONTEXT_MAX_CHARS,
+} from "./types.ts";
+
+/** An empty ref means no model has been selected yet. */
+const configuredModelRef = (value: string | undefined): string | undefined =>
+  value?.trim() || undefined;
+
+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]
+      )
+  );
+};
+
+const nonNegativeSafeInteger = (value: unknown): value is number =>
+  typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+
+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 =>
+  nonNegativeSafeInteger(value);
+
+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 =>
+  nonNegativeSafeInteger(value);
+
+export const isValidToolResultMaxBytes = (value: unknown): value is number =>
+  nonNegativeSafeInteger(value);
+
+/** One declarative entry per AdvisorConfig key: JSON type, persistence, and
+ * the live runtime value behind it. Validation and storage derive from this
+ * table; adding a setting means adding exactly one entry here. */
+export interface ConfigKeySchema {
+  /** Human-readable accepted-value phrase for error messages. */
+  accepted: string;
+  /** Live runtime value captured by saveConfig. */
+  current: () => unknown;
+  /** Included in the state captured and diffed by saveConfig. */
+  persisted: boolean;
+  /** JSON value type used for the base type check. */
+  type: "string" | "boolean" | "number" | "enum" | "object";
+  /** Type beyond the JSON type, for enum and object keys. */
+  validate?: (value: unknown) => boolean;
+}
+
+export const CONFIG_SCHEMA = {
+  advisor: {
+    accepted: "a provider/model string",
+    current: () => configuredModelRef(advisorRef),
+    persisted: true,
+    type: "string",
+  },
+  advisorAutoLoopGate: {
+    accepted: "true or false",
+    current: () => advisorAutoLoopGateRef,
+    persisted: true,
+    type: "boolean",
+  },
+  advisorBlockOnBlocked: {
+    accepted: "true or false",
+    current: () => advisorBlockOnBlockedRef,
+    persisted: true,
+    type: "boolean",
+  },
+  advisorCollapseResponses: {
+    accepted: "true or false",
+    current: () => advisorCollapseResponsesRef,
+    persisted: true,
+    type: "boolean",
+  },
+  advisorCompletionGate: {
+    accepted: "true or false",
+    current: () => advisorCompletionGateRef,
+    persisted: true,
+    type: "boolean",
+  },
+  advisorCustomInvocation: {
+    accepted: "a string",
+    current: () => advisorCustomInvocationRef,
+    persisted: true,
+    type: "string",
+  },
+  advisorEffort: {
+    accepted: "a string",
+    current: () => advisorEffortRef,
+    persisted: true,
+    type: "string",
+  },
+  advisorFailureGate: {
+    accepted: "true or false",
+    current: () => advisorFailureGateRef,
+    persisted: true,
+    type: "boolean",
+  },
+  advisorGitContext: {
+    accepted: GIT_CONTEXT_LEVELS.join(", "),
+    current: () => advisorGitContextRef,
+    persisted: true,
+    type: "enum",
+    validate: isValidGitContextLevel,
+  },
+  advisorGitContextMaxChars: {
+    accepted: "a non-negative safe integer",
+    current: () => advisorGitContextMaxCharsRef,
+    persisted: true,
+    type: "number",
+    validate: nonNegativeSafeInteger,
+  },
+  advisorHerdrIntegration: {
+    accepted: "true or false",
+    current: () => advisorHerdrIntegrationRef,
+    persisted: true,
+    type: "boolean",
+  },
+  advisorLoopThreshold: {
+    accepted: "a safe integer of at least 2",
+    current: () => advisorLoopThresholdRef,
+    persisted: true,
+    type: "number",
+    validate: isValidLoopThreshold,
+  },
+  advisorMaxCallsPerSession: {
+    accepted: "a non-negative safe integer",
+    current: () => advisorMaxCallsPerSessionRef,
+    persisted: true,
+    type: "number",
+    validate: isValidMaxCallsPerSession,
+  },
+  advisorOutcomeLogging: {
+    accepted: "true or false",
+    current: () => advisorOutcomeLoggingRef,
+    persisted: false,
+    type: "boolean",
+  },
+  advisorPlanGate: {
+    accepted: "true or false",
+    current: () => advisorPlanGateRef,
+    persisted: true,
+    type: "boolean",
+  },
+  advisorRedactSecrets: {
+    accepted: "true or false",
+    current: () => advisorRedactSecretsRef,
+    persisted: true,
+    type: "boolean",
+  },
+  advisorScoutEnabled: {
+    accepted: "true or false",
+    current: () => advisorScoutEnabledRef,
+    persisted: true,
+    type: "boolean",
+  },
+  advisorSessionSummary: {
+    accepted: "true or false",
+    current: () => advisorSessionSummaryRef,
+    persisted: true,
+    type: "boolean",
+  },
+  advisorToolPolicies: {
+    accepted:
+      "a JSON object with non-empty tool names and full, summary, or exclude values",
+    current: () => ({ ...advisorToolPoliciesRef }),
+    persisted: true,
+    type: "object",
+    validate: isValidAdvisorToolPolicies,
+  },
+  advisorToolResultMaxBytes: {
+    accepted: "a non-negative safe integer",
+    current: () => advisorToolResultMaxBytesRef,
+    persisted: true,
+    type: "number",
+    validate: isValidToolResultMaxBytes,
+  },
+  advisorToolResultMaxLines: {
+    accepted: "a non-negative safe integer",
+    current: () => advisorToolResultMaxLinesRef,
+    persisted: true,
+    type: "number",
+    validate: isValidToolResultMaxLines,
+  },
+  advisorTrackedFileContent: {
+    accepted: "true or false",
+    current: () => advisorTrackedFileContentRef,
+    persisted: true,
+    type: "boolean",
+  },
+  advisorUntrackedContent: {
+    accepted: "true or false",
+    current: () => advisorUntrackedContentRef,
+    persisted: true,
+    type: "boolean",
+  },
+  alwaysOn: {
+    accepted: "true or false",
+    current: () => alwaysOnRef,
+    persisted: true,
+    type: "boolean",
+  },
+  contextMaxChars: {
+    accepted: `a safe integer from 0 through ${MAX_CONTEXT_MAX_CHARS}`,
+    current: () => contextMaxCharsRef,
+    persisted: true,
+    type: "number",
+    validate: isValidContextMaxChars,
+  },
+  executor: {
+    accepted: "a provider/model string",
+    current: () => configuredModelRef(executorRef),
+    persisted: true,
+    type: "string",
+  },
+  executorEffort: {
+    accepted: "a string",
+    current: () => executorEffortRef,
+    persisted: true,
+    type: "string",
+  },
+  gateFailureMode: {
+    accepted: GATE_FAILURE_MODES.join(", "),
+    current: () => advisorFailureModeRef,
+    persisted: true,
+    type: "enum",
+    validate: isValidGateFailureMode,
+  },
+  showUsageDetails: {
+    accepted: "true or false",
+    current: () => showUsageDetailsRef,
+    persisted: true,
+    type: "boolean",
+  },
+  showUsageFooter: {
+    accepted: "true or false",
+    current: () => showUsageFooterRef,
+    persisted: true,
+    type: "boolean",
+  },
+  simpleMode: {
+    accepted: "true or false",
+    current: () => simpleModeRef,
+    persisted: true,
+    type: "boolean",
+  },
+} as const satisfies Record<keyof AdvisorConfig, ConfigKeySchema>;
+
+export type ConfigKey = keyof typeof CONFIG_SCHEMA;
+
+/** Keys saveConfig captures, diffs, and writes to advisor.json. */
+export type PersistedConfigKey = {
+  [Key in ConfigKey]: (typeof CONFIG_SCHEMA)[Key]["persisted"] extends true
+    ? Key
+    : never;
+}[ConfigKey];
+
+export const SAVED_CONFIG_KEYS = (
+  Object.keys(CONFIG_SCHEMA) as ConfigKey[]
+).filter(
+  (key) => CONFIG_SCHEMA[key].persisted
+) as readonly PersistedConfigKey[];
+
+/** Widened per-key view for consumers that index by dynamic key. */
+const SCHEMA_BY_KEY: Record<ConfigKey, ConfigKeySchema> = CONFIG_SCHEMA;
+
+export { configuredModelRef, SCHEMA_BY_KEY };

package/src/config/state.ts

@@ -1,4 +1,4 @@
-import type { GitContextLevel } from "../git.js";
+import type { GitContextLevel } from "../git.ts";
 import {
   type AdvisorToolPolicies,
   DEFAULT_ADVISOR_GIT_CONTEXT_MAX_CHARS,
@@ -6,7 +6,7 @@ import {
   DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES,
   DEFAULT_CONTEXT_MAX_CHARS,
   type GateFailureMode,
-} from "./types.js";
+} from "./types.ts";
 
 // An empty ref means no model has been selected yet.
 export let executorRef = "";

package/src/config/storage.ts

@@ -5,43 +5,16 @@ import {
   type ExtensionContext,
   getAgentDir,
 } from "@earendil-works/pi-coding-agent";
-import { applyConfig, resetDefaults } from "./defaults.js";
+import { applyConfig, resetDefaults } from "./defaults.ts";
 import {
-  advisorAutoLoopGateRef,
-  advisorBlockOnBlockedRef,
-  advisorCollapseResponsesRef,
-  advisorCompletionGateRef,
-  advisorCustomInvocationRef,
-  advisorEffortRef,
-  advisorFailureGateRef,
-  advisorFailureModeRef,
-  advisorGitContextMaxCharsRef,
-  advisorGitContextRef,
-  advisorHerdrIntegrationRef,
-  advisorLoopThresholdRef,
-  advisorMaxCallsPerSessionRef,
-  advisorPlanGateRef,
-  advisorRedactSecretsRef,
-  advisorRef,
-  advisorScoutEnabledRef,
-  advisorSessionSummaryRef,
-  advisorToolPoliciesRef,
-  advisorToolResultMaxBytesRef,
-  advisorToolResultMaxLinesRef,
-  advisorTrackedFileContentRef,
-  advisorUntrackedContentRef,
-  alwaysOnRef,
-  contextMaxCharsRef,
-  executorEffortRef,
-  executorRef,
-  setAdvisorOutcomeLoggingRef,
-  setPersistedModelRefs,
-  showUsageDetailsRef,
-  showUsageFooterRef,
-  simpleModeRef,
-} from "./state.js";
-import type { AdvisorConfig } from "./types.js";
-import { unknownConfigKeys, validateConfig } from "./validation.js";
+  CONFIG_SCHEMA,
+  configuredModelRef,
+  type PersistedConfigKey,
+  SAVED_CONFIG_KEYS,
+} from "./schema.ts";
+import { setAdvisorOutcomeLoggingRef, setPersistedModelRefs } from "./state.ts";
+import type { AdvisorConfig } from "./types.ts";
+import { unknownConfigKeys, validateConfig } from "./validation.ts";
 
 export const configPaths = (ctx: ExtensionContext) => [
   ctx.isProjectTrusted()
@@ -50,22 +23,71 @@ export const configPaths = (ctx: ExtensionContext) => [
   join(getAgentDir(), "advisor.json"),
 ];
 
-const configuredModelRef = (value: string | undefined): string | undefined =>
-  value?.trim() || undefined;
+type SavedConfigKey = PersistedConfigKey;
+type ConfigState = {
+  [Key in SavedConfigKey]: AdvisorConfig[Key];
+};
 
-const readConfig = (path: string): AdvisorConfig => {
+const currentConfigState = (): ConfigState =>
+  Object.fromEntries(
+    SAVED_CONFIG_KEYS.map((key) => [key, CONFIG_SCHEMA[key].current()])
+  ) as ConfigState;
+
+const sameConfigValue = <Value>(left: Value, right: Value) =>
+  JSON.stringify(left) === JSON.stringify(right);
+
+const readExistingConfig = (path: string): Record<string, unknown> => {
   try {
-    const config = JSON.parse(readFileSync(path, "utf8"));
-    validateConfig(config, path);
-    return config;
-  } catch (error) {
-    throw error instanceof Error ? error : new Error(String(error));
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : {};
+  } catch {
+    return {};
   }
 };
 
-// loadConfig runs on every tool call and every consultation. Caching the parsed
-// file by path and stat identity removes that read and parse from the hot path
-// while still applying the full reset-then-apply sequence on each call.
+const shouldPersistConfigKey = (
+  key: SavedConfigKey,
+  persistAdvisor: boolean,
+  persistExecutor: boolean
+) =>
+  (key !== "advisor" || persistAdvisor) &&
+  (key !== "executor" || persistExecutor);
+
+const applyChangedConfigValues = (
+  data: Record<string, unknown>,
+  current: ConfigState,
+  changedKeys: readonly SavedConfigKey[],
+  persistAdvisor: boolean,
+  persistExecutor: boolean
+) => {
+  for (const key of changedKeys) {
+    if (!shouldPersistConfigKey(key, persistAdvisor, persistExecutor)) {
+      continue;
+    }
+    const value = current[key];
+    const isEmptyModelRef = (key === "advisor" || key === "executor") && !value;
+    if (value === undefined || isEmptyModelRef) {
+      delete data[key];
+    } else {
+      data[key] = value;
+    }
+  }
+};
+
+// Tracks the last load/save state so a later save merges fresh disk contents instead of overwriting an external edit.
+let loadedConfigState: ConfigState | undefined;
+let loadedConfigPath: string | undefined;
+
+const readConfig = (path: string): AdvisorConfig => {
+  const config = JSON.parse(readFileSync(path, "utf8"));
+  validateConfig(config, path);
+  return config;
+};
+
+// loadConfig runs per tool call and consultation; caching by path and stat
+// identity keeps the parse off the hot path while still reset-applying each call.
 const configCache = new Map<
   string,
   { config: AdvisorConfig; identity: string }
@@ -135,10 +157,17 @@ export const loadConfig = (_ctx: ExtensionContext) => {
   // prompts, gates, budgets, disclosure, redaction, integrations, and consent
   // remain under the user's global Pi configuration.
   setAdvisorOutcomeLoggingRef(globalConfig?.advisorOutcomeLogging === true);
+  loadedConfigState = currentConfigState();
+  loadedConfigPath = global;
   return existsSync(global) ? global : null;
 };
 
-/** Saves user-controlled configuration globally without outcome consent. */
+/**
+ * Saves user-controlled configuration globally without outcome consent.
+ *
+ * Only values changed since the last load/save are written. This lets an
+ * external edit to advisor.json coexist with a later settings or model save.
+ */
 export interface SaveConfigOptions {
   persistAdvisor?: boolean;
   persistExecutor?: boolean;
@@ -151,70 +180,51 @@ export const saveConfig = (
   const path = join(getAgentDir(), "advisor.json");
   const persistAdvisor = options.persistAdvisor ?? true;
   const persistExecutor = options.persistExecutor ?? true;
-  let existing: Record<string, unknown> = {};
-  try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      existing = parsed as Record<string, unknown>;
-    }
-  } catch {
-    /* replace a missing or malformed file */
-  }
-  if (advisorMaxCallsPerSessionRef === undefined) {
-    existing.advisorMaxCallsPerSession = undefined;
+  const existing = readExistingConfig(path);
+  const current = currentConfigState();
+  const baseline = loadedConfigPath === path ? loadedConfigState : undefined;
+  const changedKeys = baseline
+    ? SAVED_CONFIG_KEYS.filter(
+        (key) => !sameConfigValue(current[key], baseline[key])
+      )
+    : [...SAVED_CONFIG_KEYS];
+  if (changedKeys.length === 0) {
+    return path;
   }
-  const data = {
-    ...existing,
-    ...(persistAdvisor && advisorRef ? { advisor: advisorRef } : {}),
-    advisorAutoLoopGate: advisorAutoLoopGateRef,
-    advisorBlockOnBlocked: advisorBlockOnBlockedRef,
-    advisorCollapseResponses: advisorCollapseResponsesRef,
-    advisorCompletionGate: advisorCompletionGateRef,
-    advisorCustomInvocation: advisorCustomInvocationRef,
-    advisorEffort: advisorEffortRef,
-    advisorFailureGate: advisorFailureGateRef,
-    advisorLoopThreshold: advisorLoopThresholdRef,
-    advisorPlanGate: advisorPlanGateRef,
-    contextMaxChars: contextMaxCharsRef,
-    ...(persistExecutor && executorRef ? { executor: executorRef } : {}),
-    executorEffort: executorEffortRef,
-    ...(advisorMaxCallsPerSessionRef === undefined
-      ? {}
-      : { advisorMaxCallsPerSession: advisorMaxCallsPerSessionRef }),
-    advisorGitContext: advisorGitContextRef,
-    advisorGitContextMaxChars: advisorGitContextMaxCharsRef,
-    advisorHerdrIntegration: advisorHerdrIntegrationRef,
-    advisorRedactSecrets: advisorRedactSecretsRef,
-    advisorScoutEnabled: advisorScoutEnabledRef,
-    advisorSessionSummary: advisorSessionSummaryRef,
-    advisorToolPolicies: advisorToolPoliciesRef,
-    advisorToolResultMaxBytes: advisorToolResultMaxBytesRef,
-    advisorToolResultMaxLines: advisorToolResultMaxLinesRef,
-    advisorTrackedFileContent: advisorTrackedFileContentRef,
-    advisorUntrackedContent: advisorUntrackedContentRef,
-    alwaysOn: alwaysOnRef,
-    gateFailureMode: advisorFailureModeRef,
-    showUsageDetails: showUsageDetailsRef,
-    showUsageFooter: showUsageFooterRef,
-    simpleMode: simpleModeRef,
-  };
+  const data = { ...existing };
+  applyChangedConfigValues(
+    data,
+    current,
+    changedKeys,
+    persistAdvisor,
+    persistExecutor
+  );
   writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`);
   resetConfigCache();
+  const nextLoadedState = { ...current };
+  if (!persistAdvisor) {
+    nextLoadedState.advisor = baseline
+      ? baseline.advisor
+      : configuredModelRef(
+          typeof existing.advisor === "string" ? existing.advisor : undefined
+        );
+  }
+  if (!persistExecutor) {
+    nextLoadedState.executor = baseline
+      ? baseline.executor
+      : configuredModelRef(
+          typeof existing.executor === "string" ? existing.executor : undefined
+        );
+  }
+  loadedConfigState = nextLoadedState;
+  loadedConfigPath = path;
   return path;
 };
 
 /** Outcome logging is deliberately written only to the global Pi configuration. */
 export const saveGlobalOutcomeLogging = (enabled: boolean) => {
   const path = join(getAgentDir(), "advisor.json");
-  let existing: Record<string, unknown> = {};
-  try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      existing = parsed as Record<string, unknown>;
-    }
-  } catch {
-    /* create it */
-  }
+  const existing = readExistingConfig(path);
   writeFileSync(
     path,
     `${JSON.stringify({ ...existing, advisorOutcomeLogging: enabled }, null, 2)}\n`

package/src/config/types.ts

@@ -2,7 +2,7 @@ import {
   DEFAULT_MAX_BYTES,
   DEFAULT_MAX_LINES,
 } from "@earendil-works/pi-coding-agent";
-import type { GitContextLevel } from "../git.js";
+import type { GitContextLevel } from "../git.ts";
 
 export const DEFAULT_CONTEXT_MAX_CHARS = 15_000;
 export const MAX_CONTEXT_MAX_CHARS = Number.MAX_SAFE_INTEGER;