pi-advisor-flow 0.5.6 → 0.7.0

package/src/tools/consultation.ts

@@ -3,201 +3,60 @@ import type { Message } from "@earendil-works/pi-ai/compat";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
   advisorEffortRef,
-  advisorGitContextMaxCharsRef,
-  advisorGitContextRef,
   advisorRedactSecretsRef,
   advisorRef,
-  advisorScoutEnabledRef,
-  advisorTrackedFileContentRef,
-  advisorUntrackedContentRef,
-  contextMaxCharsRef,
-  executorRef,
-} from "../config/state.js";
-import { loadConfig } from "../config/storage.js";
-import { redactAndCapText, redactSecrets } from "../conversation.js";
-import {
-  clampGitContextLevel,
-  collectGitContext,
-  type GitContextLevel,
-} from "../git.js";
-import { collectTextStream, resolveConfiguredModel } from "../model-stream.js";
-import { readProjectPreferences } from "../preferences.js";
-import {
-  runAdvisorScout,
-  type ScoutLifecycleEvent,
-  type ScoutOutcome,
-} from "../scout.js";
-import {
-  buildScoutManifest,
-  reconstructScoutConversation,
-  SCOUT_MANIFEST_MAX_BYTES,
-} from "../scout-context.js";
-import type { ConsultationTrigger, GateTrigger } from "../session-state.js";
-import { readTrackedFiles, readUntrackedFiles } from "../untracked.js";
-import { parseAutomaticDecision } from "./gate-protocol.js";
+} from "../config/state.ts";
+import { loadConfig } from "../config/storage.ts";
+import type { GitContextLevel } from "../git.ts";
+import { collectTextStream, resolveConfiguredModel } from "../model-stream.ts";
+import { redactSecrets } from "../redaction.ts";
+import type { ScoutLifecycleEvent } from "../scout.ts";
+import type { ConsultationTrigger, GateTrigger } from "../session-state.ts";
+import { assembleConsultationContext } from "./consult-context.ts";
+import { parseAutomaticDecision } from "./gate-protocol.ts";
 import {
   ADVISOR_DECISION_SYSTEM,
   ADVISOR_SYSTEM,
-  advisorGitContextBudget,
   advisorMessageText,
-  advisorRepositoryContext,
-  advisorRequestConversation,
-} from "./prompts.js";
-import type { AdvisorConsultationResult, AdvisorGateOutcome } from "./types.js";
+} from "./prompts.ts";
+import type { AdvisorConsultationResult, AdvisorGateOutcome } from "./types.ts";
 
-export const curateAdvisorConversation = async (
-  ctx: ExtensionContext,
-  legacyConversation: string,
-  signal?: AbortSignal,
-  onScout?: (event: ScoutLifecycleEvent) => void,
-  enabled = advisorScoutEnabledRef,
-  runScout: typeof runAdvisorScout = runAdvisorScout,
-  currentInvocationId?: string,
-  maxChars?: number
-): Promise<{
-  conversation: string;
-  scout?: Exclude<ScoutOutcome, { cancelled: true }>;
-}> => {
-  if (!enabled) {
-    return { conversation: legacyConversation };
-  }
-  if (maxChars !== undefined && maxChars <= 0) {
-    return { conversation: "" };
-  }
-  const built = buildScoutManifest(ctx, {
-    currentInvocationId,
-    maxConversationChars: maxChars,
-    maxManifestBytes: SCOUT_MANIFEST_MAX_BYTES,
-  });
-  if (!built.ok) {
-    const scout: Exclude<ScoutOutcome, { cancelled: true }> = {
-      category: built.reason,
-      message: built.message,
-      metrics: {
-        availableCount: 0,
-        inputBytes: 0,
-        latencyMs: 0,
-        omittedBeforeScout: 0,
-        selectedCount: 0,
-      },
-      model: executorRef,
-      ok: false,
-    };
-    onScout?.({ outcome: scout, type: "fallback" });
-    return { conversation: legacyConversation, scout };
-  }
-  const outcome = await runScout(
-    ctx,
-    built.manifest,
-    signal,
-    onScout,
-    undefined,
-    undefined
-  );
-  if (!outcome.ok && outcome.cancelled) {
-    throw signal?.reason instanceof Error
-      ? signal.reason
-      : new Error("Advisor operation cancelled during Scout.");
-  }
-  let conversation = legacyConversation;
-  if (outcome.ok) {
-    conversation =
-      maxChars === undefined
-        ? outcome.conversation
-        : reconstructScoutConversation(
-            built.manifest,
-            outcome.selection.selectedIds,
-            outcome.selection.synthesis,
-            maxChars
-          );
+// biome-ignore lint/performance/noBarrelFile: preserves the tools facade's historical re-export of the moved curation entry point.
+export { curateAdvisorConversation } from "../scout-curation.ts";
+
+/** Thrown when the Advisor produced an empty response body. */
+class AdvisorNoAdviceError extends Error {
+  constructor() {
+    super("Advisor returned no advice.");
+    this.name = "AdvisorNoAdviceError";
   }
-  return { conversation, scout: outcome };
-};
+}
+
+interface CollectAdvisorResponseOptions {
+  ctx: ExtensionContext;
+  currentInvocationId?: string;
+  draft?: string;
+  gitContext?: GitContextLevel;
+  includeTracked?: string[];
+  includeUntracked?: string[];
+  onChunk?: (thinking: string, text: string) => void;
+  onScout?: (event: ScoutLifecycleEvent) => void;
+  question?: string;
+  signal?: AbortSignal;
+  systemPrompt: string;
+}
+
+const fileTag = (item: { path: string; text: string }) =>
+  `<file path=${JSON.stringify(item.path)}>\n${item.text}\n</file>`;
 
 const collectAdvisorResponse = async (
-  ctx: ExtensionContext,
-  systemPrompt: string,
-  question: string | undefined,
-  signal: AbortSignal | undefined,
-  onChunk: ((thinking: string, text: string) => void) | undefined,
-  gitContext?: GitContextLevel,
-  draft?: string,
-  includeUntracked?: string[],
-  includeTracked?: string[],
-  onScout?: (event: ScoutLifecycleEvent) => void,
-  currentInvocationId?: string
+  options: CollectAdvisorResponseOptions
 ) => {
+  const { ctx, question, signal, systemPrompt } = options;
   loadConfig(ctx);
   const resolved = await resolveConfiguredModel(ctx, advisorRef, "Advisor");
+  const context = await assembleConsultationContext(options);
 
-  // The user setting is the ceiling; the Executor may only narrow it.
-  const allowed = advisorGitContextRef;
-  const level = clampGitContextLevel(gitContext ?? allowed, allowed);
-  const gitBudget = advisorGitContextBudget(
-    contextMaxCharsRef,
-    advisorGitContextMaxCharsRef
-  );
-  const changes = collectGitContext(
-    ctx.cwd,
-    level,
-    gitBudget,
-    advisorRedactSecretsRef ? redactSecrets : undefined
-  );
-  // The note is placed first so a cap can never drop the statement that the
-  // Advisor's view of the repository is limited.
-  // The disclosure warning is control metadata, not repository payload. Keep it
-  // outside the zero-byte Git budget so disabling disclosure cannot erase it.
-  const changeText = advisorRepositoryContext(
-    changes,
-    gitContext ?? allowed,
-    level,
-    gitBudget
-  );
-  // Repository context spends part of the shared budget, so a large patch
-  // cannot silently push the conversation past the model's context window.
-  const conversationBudget = Math.max(
-    0,
-    contextMaxCharsRef - changeText.length
-  );
-  const legacyConversation = advisorRequestConversation(
-    ctx,
-    conversationBudget
-  );
-  const curated = await curateAdvisorConversation(
-    ctx,
-    legacyConversation,
-    signal,
-    onScout,
-    advisorScoutEnabledRef,
-    runAdvisorScout,
-    currentInvocationId,
-    conversationBudget
-  );
-  const { conversation, scout } = curated;
-  const preferences = await readProjectPreferences(
-    ctx,
-    8 * 1024,
-    advisorRedactSecretsRef
-  );
-  const draftText = draft
-    ? redactAndCapText(draft, 8 * 1024, advisorRedactSecretsRef)
-    : undefined;
-  const untracked = await readUntrackedFiles(
-    ctx.cwd,
-    includeUntracked ?? [],
-    advisorUntrackedContentRef,
-    advisorRedactSecretsRef
-  );
-  const tracked = await readTrackedFiles(
-    ctx.cwd,
-    includeTracked ?? [],
-    advisorTrackedFileContentRef,
-    advisorRedactSecretsRef,
-    Math.max(
-      0,
-      24 * 1024 - untracked.reduce((sum, item) => sum + item.bytes, 0)
-    )
-  );
   // Keep the original question available to local UI callers, but never send
   // its credential-shaped values to the provider when redaction is enabled.
   const outboundQuestion =
@@ -209,19 +68,13 @@ const collectAdvisorResponse = async (
       content: [
         {
           text: advisorMessageText(
-            conversation,
+            context.conversation,
             outboundQuestion,
-            changeText,
-            draftText,
-            preferences?.text,
-            untracked.map(
-              (item) =>
-                `<file path=${JSON.stringify(item.path)}>\n${item.text}\n</file>`
-            ),
-            tracked.map(
-              (item) =>
-                `<file path=${JSON.stringify(item.path)}>\n${item.text}\n</file>`
-            )
+            context.changeText,
+            context.draftText,
+            context.preferences?.text,
+            context.untracked.map(fileTag),
+            context.tracked.map(fileTag)
           ),
           type: "text",
         },
@@ -233,27 +86,29 @@ const collectAdvisorResponse = async (
 
   const streamed = await collectTextStream(resolved, {
     messages,
-    onChunk,
+    onChunk: options.onChunk,
     reasoning: advisorEffortRef,
     signal,
     systemPrompt,
   });
   const markdown = streamed.text;
   if (!markdown.trim()) {
-    throw new Error("Advisor returned no advice.");
+    throw new AdvisorNoAdviceError();
   }
   return {
-    draftBytes: draftText ? Buffer.byteLength(draftText, "utf8") : undefined,
+    draftBytes: context.draftText
+      ? Buffer.byteLength(context.draftText, "utf8")
+      : undefined,
     markdown,
     model: advisorRef,
-    preferenceBytes: preferences?.bytes,
+    preferenceBytes: context.preferences?.bytes,
     thinkingText: streamed.thinking,
     trackedBytes:
-      tracked.reduce((sum, item) => sum + item.bytes, 0) || undefined,
+      context.tracked.reduce((sum, item) => sum + item.bytes, 0) || undefined,
     untrackedBytes:
-      untracked.reduce((sum, item) => sum + item.bytes, 0) || undefined,
+      context.untracked.reduce((sum, item) => sum + item.bytes, 0) || undefined,
     usage: streamed.usage,
-    ...(scout ? { scout } : {}),
+    ...(context.scout ? { scout: context.scout } : {}),
   };
 };
 
@@ -270,19 +125,19 @@ export const consultAdvisor = async (
   onScout?: (event: ScoutLifecycleEvent) => void,
   currentInvocationId?: string
 ): Promise<AdvisorConsultationResult> => {
-  const result = await collectAdvisorResponse(
+  const result = await collectAdvisorResponse({
     ctx,
-    ADVISOR_SYSTEM,
-    question,
-    signal,
-    onChunk,
-    gitContext,
+    currentInvocationId,
     draft,
-    includeUntracked,
+    gitContext,
     includeTracked,
+    includeUntracked,
+    onChunk,
     onScout,
-    currentInvocationId
-  );
+    question,
+    signal,
+    systemPrompt: ADVISOR_SYSTEM,
+  });
   return { ...result, adviceId: randomUUID(), trigger };
 };
 
@@ -296,19 +151,15 @@ export const runAdvisorGate = async (
   currentInvocationId?: string
 ): Promise<AdvisorGateOutcome> => {
   try {
-    const result = await collectAdvisorResponse(
+    const result = await collectAdvisorResponse({
       ctx,
-      ADVISOR_DECISION_SYSTEM,
-      question,
-      signal,
+      currentInvocationId,
       onChunk,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
       onScout,
-      currentInvocationId
-    );
+      question,
+      signal,
+      systemPrompt: ADVISOR_DECISION_SYSTEM,
+    });
     const parsed = parseAutomaticDecision(result.markdown);
     if (!parsed.ok) {
       return { ...parsed, usage: result.usage };
@@ -327,7 +178,7 @@ export const runAdvisorGate = async (
     const message = error instanceof Error ? error.message : String(error);
     return {
       category:
-        message === "Advisor returned no advice."
+        error instanceof AdvisorNoAdviceError
           ? "empty-response"
           : "provider-error",
       message,

package/src/tools/gate-policy.ts

@@ -8,11 +8,11 @@ import {
   getAdvisorMaxCallsPerSession,
   getAdvisorSettings,
   isSimpleMode,
-} from "../config/state.js";
-import type { GateFailureMode } from "../config/types.js";
-import { herdrAdvisorBlock, notifyHerdrAdvisorFailure } from "../herdr.js";
-import type { AdvisorSessionState } from "../session-state.js";
-import type { AdvisorGateResult, GateFailureCategory } from "./types.js";
+} from "../config/state.ts";
+import type { GateFailureMode } from "../config/types.ts";
+import { herdrAdvisorBlock, notifyHerdrAdvisorFailure } from "../herdr.ts";
+import type { AdvisorSessionState } from "../session-state.ts";
+import type { AdvisorGateResult, GateFailureCategory } from "./types.ts";
 
 export const updateAdvisorUsageStatus = (
   ctx: ExtensionContext,

package/src/tools/gate-protocol.ts

@@ -1,5 +1,5 @@
-import type { GateDecision } from "../session-state.js";
-import type { AdvisorGateFailure, AdvisorGateResult } from "./types.js";
+import type { GateDecision } from "../session-state.ts";
+import type { AdvisorGateFailure, AdvisorGateResult } from "./types.ts";
 
 const DECISION_LINE = /^Decision\s*:\s*(proceed|revise|blocked)\s*$/i;
 const CODE_FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;

package/src/tools/jev-filter.ts

@@ -0,0 +1,202 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Fetch } from "@typesafe-ai/sdk";
+import {
+  advisorJevFilterEnabledRef,
+  advisorJevFilterNoulMarginRef,
+  advisorJevFilterOverrideWindowRef,
+  advisorJevFilterSkipConfidenceRef,
+  isSimpleMode,
+} from "../config/state.ts";
+import { JevFailure, jevClientFromCredentials } from "../jev/client.ts";
+import { consumePlaintextKeyWarning } from "../jev/key-store.ts";
+import {
+  composeScreeningVerdict,
+  screeningQuestions,
+} from "../jev/questions.ts";
+import { buildJevState } from "../jev/state.ts";
+import { type JevCredentials, resolveJevTransport } from "../jev/transport.ts";
+import type { AdvisorSessionState } from "../session-state.ts";
+import { createOutageNotifier } from "./outage-notifier.ts";
+
+export type JevSkipKind = "screened" | "repeat";
+
+export type ScreeningOutcome =
+  | { decision: "allow" }
+  | {
+      decision: "skip";
+      kind: JevSkipKind;
+      reason: string;
+      reattachedAdvice?: string;
+    };
+
+export interface ScreenConsultationOptions {
+  draft?: string;
+  force?: boolean;
+  question?: string;
+  signal?: AbortSignal;
+}
+
+export interface ScreeningDeps {
+  fetch?: Fetch;
+  resolveTransport?: () => Promise<JevCredentials | undefined>;
+}
+
+export const normalizeScreeningQuestion = (question: string | undefined) =>
+  question?.trim().toLowerCase().replace(/\s+/g, " ") || undefined;
+
+const REATTACHED_ADVICE_CAP_BYTES = 4 * 1024;
+
+const SCREENED_SKIP_TEXT =
+  "Advisor consultation skipped (screened out): the stakes are low and you can resolve this yourself with available tools and context. Proceed on your own judgment with what you already have.";
+
+const repeatSkipText = (advice: string) =>
+  `Advisor consultation skipped (already answered): this question was answered earlier in this session; the earlier advice is reattached below. Consult again only if the situation has materially changed.\n\n${advice}`;
+
+const outageNotifier = createOutageNotifier(
+  (category, message) =>
+    `Advisor Jev filter failed (${category}); allowing consultations. ${message}`
+);
+
+const notifyOutageOnce = outageNotifier.notify;
+
+/** Test-only: re-arms the once-per-outage notification. */
+export const resetJevOutageNotification = outageNotifier.reset;
+
+const allow = (): ScreeningOutcome => ({ decision: "allow" });
+
+/**
+ * Fail-open screening: decides run/skip for one ask_advisor call. Disabled or
+ * simple mode, missing credentials, and every Jev failure allow the
+ * consultation; only the hard conjunction (negligible-mass ≥ skip confidence
+ * AND confidently self-answerable) or an exact repeat skips.
+ */
+export const screenConsultation = (
+  ctx: ExtensionContext,
+  session: AdvisorSessionState,
+  options: ScreenConsultationOptions,
+  deps: ScreeningDeps = {}
+): Promise<ScreeningOutcome> => {
+  if (isSimpleMode()) {
+    return Promise.resolve(allow());
+  }
+  // Repeat reattachment and its force/passthrough escape hatch are code-side
+  // and free: they run regardless of the Jev enable flag, which only gates
+  // the (paid, network) Jev screening call.
+  const normalizedQuestion = normalizeScreeningQuestion(options.question);
+  const bypass = bypassOutcome(session, options, normalizedQuestion);
+  if (bypass) {
+    return Promise.resolve(bypass);
+  }
+  const reattached = session.reattachedAdviceFor(normalizedQuestion);
+  if (reattached) {
+    session.recordJevFilterSkipped(true, normalizedQuestion);
+    return Promise.resolve({
+      decision: "skip",
+      kind: "repeat",
+      reason: "already answered earlier in this session",
+      reattachedAdvice: reattached.slice(0, REATTACHED_ADVICE_CAP_BYTES),
+    });
+  }
+  if (!advisorJevFilterEnabledRef) {
+    return Promise.resolve(allow());
+  }
+  return screenWithJev(ctx, session, options, deps, normalizedQuestion);
+};
+
+const bypassOutcome = (
+  session: AdvisorSessionState,
+  options: ScreenConsultationOptions,
+  normalizedQuestion: string | undefined
+): ScreeningOutcome | undefined => {
+  const lastSkip = session.lastJevSkip;
+  if (options.force) {
+    if (
+      lastSkip?.normalizedQuestion !== undefined &&
+      lastSkip.normalizedQuestion === normalizedQuestion
+    ) {
+      session.recordJevFilterOverride();
+    }
+    return allow();
+  }
+  if (
+    normalizedQuestion !== undefined &&
+    lastSkip?.normalizedQuestion === normalizedQuestion &&
+    session.sessionTurnOrdinal - lastSkip.turn <=
+      advisorJevFilterOverrideWindowRef
+  ) {
+    session.recordJevFilterOverride();
+    return allow();
+  }
+  return undefined;
+};
+
+const screenWithJev = async (
+  ctx: ExtensionContext,
+  session: AdvisorSessionState,
+  options: ScreenConsultationOptions,
+  deps: ScreeningDeps,
+  normalizedQuestion: string | undefined
+): Promise<ScreeningOutcome> => {
+  const credentials = await (deps.resolveTransport ?? resolveJevTransport)(ctx);
+  if (!credentials) {
+    session.recordJevFilterFailure();
+    notifyOutageOnce(
+      ctx,
+      "missing-key",
+      "No Jev credentials resolved (no TypeSafe key and no OpenRouter login)."
+    );
+    return allow();
+  }
+  if (credentials.source === "advisor-json") {
+    const warning = consumePlaintextKeyWarning();
+    if (warning && ctx.hasUI) {
+      ctx.ui.notify(warning, "warning");
+    }
+  }
+
+  const client = jevClientFromCredentials(credentials, deps.fetch);
+  try {
+    const result = await client.ask(
+      buildJevState(ctx, options),
+      screeningQuestions,
+      options.signal
+    );
+    session.recordJevFilterUsage(result.usage);
+    const verdict = composeScreeningVerdict(result.answers, {
+      noulMargin: advisorJevFilterNoulMarginRef,
+      skipConfidence: advisorJevFilterSkipConfidenceRef,
+    });
+    if (verdict.skip) {
+      session.recordJevFilterSkipped(false, normalizedQuestion);
+      return {
+        decision: "skip",
+        kind: "screened",
+        reason: "low stakes and resolvable without a consultation",
+      };
+    }
+    session.recordJevFilterAllowed();
+    return allow();
+  } catch (error) {
+    session.recordJevFilterFailure();
+    if (error instanceof JevFailure) {
+      notifyOutageOnce(ctx, error.category, error.message);
+    } else if (options.signal?.aborted) {
+      throw error;
+    } else {
+      notifyOutageOnce(
+        ctx,
+        "error",
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+    return allow();
+  }
+};
+
+export const screeningSkipText = (outcome: {
+  kind: JevSkipKind;
+  reattachedAdvice?: string;
+}) =>
+  outcome.kind === "repeat" && outcome.reattachedAdvice
+    ? repeatSkipText(outcome.reattachedAdvice)
+    : SCREENED_SKIP_TEXT;