pi-advisor-flow 0.6.0 → 0.7.0

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;

package/src/tools/jev-turn-gate.ts

@@ -0,0 +1,183 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Fetch } from "@typesafe-ai/sdk";
+import {
+  advisorJevTurnGateEveryTurnsRef,
+  advisorJevTurnGateNoulThresholdRef,
+  getAdvisorMaxCallsPerSession,
+  isSimpleMode,
+} from "../config/state.ts";
+import { herdrAdvisorActivity } from "../herdr.ts";
+import { JevFailure, jevClientFromCredentials } from "../jev/client.ts";
+import { composeTurnGateVerdict } 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 { advisorUsageCost } from "../usage.ts";
+import type { consultAdvisor } from "./consultation.ts";
+import { updateAdvisorUsageStatus } from "./gate-policy.ts";
+import { createOutageNotifier } from "./outage-notifier.ts";
+
+export const turnGateQuestion = {
+  criteria: {
+    false:
+      "The executor is progressing soundly on work that matches the user's intent; interrupting would add nothing material.",
+    true: "The executor is approaching a material decision, repeating a failure, about to claim success without validation, or drifting from the user's intent; a second opinion now would change what happens next.",
+  },
+  instructions:
+    "Should a senior engineering advisor be consulted right now, before the executor continues? Judge from `recent_conversation`.",
+  type: "noul",
+} as const;
+
+export interface JevTurnGateDeps {
+  consult?: typeof consultAdvisor;
+  fetch?: Fetch;
+  resolveTransport?: () => Promise<JevCredentials | undefined>;
+}
+
+export interface JevTurnGateRegistration {
+  activeTools: () => string[];
+  consult: typeof consultAdvisor;
+  deps?: JevTurnGateDeps;
+  send: (message: {
+    content: string;
+    customType: string;
+    details: Record<string, unknown>;
+    display: boolean;
+  }) => void;
+  session: AdvisorSessionState;
+}
+
+const outageNotifier = createOutageNotifier(
+  (category, message) =>
+    `Advisor Jev turn gate failed (${category}); continuing without a proactive consultation. ${message}`
+);
+
+const notifyFailureOnce = outageNotifier.notify;
+
+/** Test-only: re-arms the once-per-outage notification. */
+export const resetJevTurnGateNotification = outageNotifier.reset;
+
+/**
+ * turn_end handler: counts turns without a consultation and, every Nth such
+ * turn, asks Jev whether the Advisor should proactively weigh in. Confident
+ * true runs a real consultation delivered as a steer message; everything else
+ * keeps the status quo.
+ */
+export const handleJevTurnEnd = async (
+  registration: JevTurnGateRegistration,
+  ctx: ExtensionContext
+): Promise<void> => {
+  const { session } = registration;
+  session.recordCompletedTurn();
+  const interval = advisorJevTurnGateEveryTurnsRef;
+  if (
+    interval <= 0 ||
+    session.turnsSinceConsultation <= 0 ||
+    session.turnsSinceConsultation % interval !== 0
+  ) {
+    return;
+  }
+  if (
+    isSimpleMode() ||
+    session.blocked ||
+    !registration.activeTools().includes("ask_advisor") ||
+    !session.canConsult(getAdvisorMaxCallsPerSession())
+  ) {
+    return;
+  }
+
+  const consult = registration.deps?.consult ?? registration.consult;
+  const deps = registration.deps ?? {};
+  try {
+    const credentials = await (deps.resolveTransport ?? resolveJevTransport)(
+      ctx
+    );
+    if (!credentials) {
+      session.recordJevGateFailure();
+      notifyFailureOnce(
+        ctx,
+        "missing-key",
+        "No Jev credentials resolved (no TypeSafe key and no OpenRouter login)."
+      );
+      return;
+    }
+    const client = jevClientFromCredentials(credentials, deps.fetch);
+    const result = await client.ask(buildJevState(ctx, {}), {
+      should_consult: turnGateQuestion,
+    });
+    session.recordJevGateCheck(result.usage);
+    const shouldConsult = composeTurnGateVerdict(
+      result.answers,
+      advisorJevTurnGateNoulThresholdRef
+    );
+    if (!shouldConsult) {
+      return;
+    }
+
+    session.consumeCall();
+    herdrAdvisorActivity.start();
+    registration.send({
+      content: "Proactive Advisor turn review",
+      customType: "advisor-turn-gate-call",
+      details: {
+        question: `Turn gate: ${session.turnsSinceConsultation} turns without a consultation`,
+        turn: session.sessionTurnOrdinal,
+      },
+      display: true,
+    });
+    try {
+      const consulted = await consult(
+        ctx,
+        undefined,
+        ctx.signal,
+        undefined,
+        "turn-gate"
+      );
+      session.recordJevGateConsultation();
+      session.resetTurnsSinceConsultation();
+      session.recordInvocation({
+        cost: advisorUsageCost(consulted.usage),
+        executionEffect: "continued",
+        kind: "markdown",
+        model: consulted.model,
+        trigger: "turn-gate",
+        usage: consulted.usage,
+      });
+      updateAdvisorUsageStatus(ctx, session);
+      registration.send({
+        content: consulted.markdown,
+        customType: "advisor-turn-gate-result",
+        details: {
+          advisor: consulted.model,
+          text: consulted.markdown,
+          usage: consulted.usage,
+        },
+        display: true,
+      });
+    } finally {
+      herdrAdvisorActivity.finish();
+    }
+  } catch (error) {
+    session.recordJevGateFailure();
+    if (error instanceof JevFailure) {
+      notifyFailureOnce(ctx, error.category, error.message);
+    } else if (!ctx.signal?.aborted) {
+      notifyFailureOnce(
+        ctx,
+        "error",
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+};
+
+/** Wires the turn_end handler on an ExtensionAPI-like surface. */
+export const registerJevTurnGate = <T extends string>(
+  on: (
+    event: T,
+    handler: (event: unknown, ctx: ExtensionContext) => unknown
+  ) => void,
+  registration: JevTurnGateRegistration
+): void => {
+  on("turn_end" as T, (_event, ctx) => handleJevTurnEnd(registration, ctx));
+};

package/src/tools/loop-gate.ts

@@ -180,6 +180,7 @@ export const handleAutomaticGate = async (
     return failure.block ? { block: true, reason: failure.reason } : undefined;
   }
   session.consumeCall();
+  session.resetTurnsSinceConsultation();
   herdrAdvisorActivity.start();
   let scoutDetails: ScoutToolDetails | undefined;
   const scoutStatusToken = Symbol("automatic-gate-scout");

package/src/tools/outage-notifier.ts

@@ -0,0 +1,30 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export interface OutageNotifier {
+  /** Notifies once per distinct category+message; records the key even headless. */
+  notify: (ctx: ExtensionContext, category: string, message: string) => void;
+  /** Test-only: re-arms the once-per-outage notification. */
+  reset: () => void;
+}
+
+/** Creates an independently stateful once-per-outage notifier. */
+export const createOutageNotifier = (
+  format: (category: string, message: string) => string
+): OutageNotifier => {
+  let lastKey: string | undefined;
+  return {
+    notify: (ctx, category, message) => {
+      const key = `${category}:${message}`;
+      if (key === lastKey) {
+        return;
+      }
+      lastKey = key;
+      if (ctx.hasUI) {
+        ctx.ui.notify(format(category, message), "warning");
+      }
+    },
+    reset: () => {
+      lastKey = undefined;
+    },
+  };
+};

package/src/tools/register-ask-advisor.ts

@@ -17,6 +17,7 @@ import {
   snapshotAdvisorUsage,
 } from "../usage.ts";
 import { notifyLocalFailure, updateAdvisorUsageStatus } from "./gate-policy.ts";
+import { normalizeScreeningQuestion, screeningSkipText } from "./jev-filter.ts";
 import { renderAdvisorResult } from "./render-advisor-result.ts";
 import {
   renderAdvisorCallBox,
@@ -52,6 +53,7 @@ export const registerAskAdvisorTool = ({
   consult: requestAdvisor,
   pi,
   reservedCalls,
+  screen,
   session,
 }: ToolRegistrationContext): void => {
   pi.registerTool({
@@ -66,9 +68,36 @@ export const registerAskAdvisorTool = ({
       ) {
         throw new Error("Advisor call budget exhausted for this session.");
       }
+      // The Jev screening seam sits after the budget re-check and before the
+      // handoff claim: a skipped call consumes neither the one-shot handoff
+      // nor the budget.
+      const normalizedQuestion = normalizeScreeningQuestion(
+        resolveAdvisorRequest(params.question)
+      );
+      const screening = await screen(ctx, session, {
+        draft: params.draft,
+        force: params.force,
+        question: resolveAdvisorRequest(params.question),
+        signal,
+      });
+      if (screening.decision === "skip") {
+        const skipText = screeningSkipText(screening);
+        return {
+          content: [{ text: skipText, type: "text" }],
+          details: {
+            jev: {
+              kind: screening.kind,
+              reason: screening.reason,
+              skipped: true,
+            },
+            text: skipText,
+          },
+        };
+      }
       claimTrackedHandoff(session, params.includeTrackedFiles);
       if (!isSimpleMode()) {
         session.consumeCall();
+        session.resetTurnsSinceConsultation();
       }
       herdrAdvisorActivity.start();
       let scoutDetails: AdvisorToolDetails["scout"];
@@ -123,7 +152,8 @@ export const registerAskAdvisorTool = ({
           result.adviceId,
           result.markdown,
           result.trigger,
-          Boolean(result.draftBytes)
+          Boolean(result.draftBytes),
+          normalizedQuestion
         );
         session.recordInvocation({
           cost: advisorUsageCost(result.usage),
@@ -189,6 +219,12 @@ export const registerAskAdvisorTool = ({
             "Concise untrusted draft for plan or completion review; claims are not verification evidence.",
         })
       ),
+      force: Type.Optional(
+        Type.Boolean({
+          description:
+            "Set true only when you judge a decision genuinely material after a consultation was screened out; bypasses screening.",
+        })
+      ),
       gitContext: Type.Optional(
         Type.Union(
           [Type.Literal("none"), Type.Literal("summary"), Type.Literal("full")],

package/src/tools/register-renderers.ts

@@ -20,6 +20,64 @@ export const registerToolRenderers = (pi: ExtensionAPI): void => {
     }
   );
 
+  pi.registerMessageRenderer?.(
+    "advisor-turn-gate-call",
+    (message, _options, theme) => {
+      const details = message.details as { question?: string } | undefined;
+      return renderAdvisorCallBox(details?.question, theme);
+    }
+  );
+
+  pi.registerMessageRenderer?.(
+    "advisor-turn-gate-result",
+    (message, { expanded }, theme) => {
+      const details = message.details as
+        | { advisor?: string; text?: string; usage?: unknown }
+        | undefined;
+      const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+      box.addChild(
+        new Text(
+          theme.fg("warning", theme.bold("◆ ADVISOR · TURN REVIEW")),
+          0,
+          0
+        )
+      );
+      if (details?.advisor) {
+        box.addChild(new Text(theme.fg("dim", `  ${details.advisor}`), 0, 0));
+      }
+      if (getAdvisorSettings().showUsageDetails) {
+        const usage = formatAdvisorUsage(details?.usage);
+        if (usage) {
+          box.addChild(new Text(theme.fg("dim", `  Usage: ${usage}`), 0, 0));
+        }
+      }
+      if (details?.text) {
+        box.addChild(
+          new Markdown(
+            adviceForDisplay(details.text, Boolean(expanded)),
+            0,
+            0,
+            getMarkdownTheme()
+          )
+        );
+      } else {
+        box.addChild(
+          new Text(
+            theme.fg(
+              "error",
+              typeof message.content === "string"
+                ? message.content
+                : "Advisor turn review failed."
+            ),
+            0,
+            0
+          )
+        );
+      }
+      return box;
+    }
+  );
+
   pi.registerMessageRenderer?.(
     "advisor-loop-call",
     (message, _options, theme) => {

package/src/tools/registration.ts

@@ -2,6 +2,8 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { appendOutcome } from "../outcomes.ts";
 import type { AdvisorSessionState } from "../session-state.ts";
 import { consultAdvisor, runAdvisorGate } from "./consultation.ts";
+import { screenConsultation } from "./jev-filter.ts";
+import { registerJevTurnGate } from "./jev-turn-gate.ts";
 import { registerAskAdvisorTool } from "./register-ask-advisor.ts";
 import { registerToolLifecycle } from "./register-lifecycle.ts";
 import { registerOutcomeTool } from "./register-outcome.ts";
@@ -25,6 +27,7 @@ export const registerAdvisorTool = (
     reservedCalls: new Set<string>(),
     runGate: dependencies.runGate ?? runAdvisorGate,
     scoutStatus: dependencies.statusManager ?? new ScoutStatusManager(),
+    screen: dependencies.screen ?? screenConsultation,
     session,
   };
 
@@ -32,4 +35,18 @@ export const registerAdvisorTool = (
   registerToolLifecycle(registration);
   registerAskAdvisorTool(registration);
   registerOutcomeTool(registration);
+  registerJevTurnGate(
+    (
+      event: Parameters<ExtensionAPI["on"]>[0],
+      handler: (event: unknown, ctx: never) => unknown
+    ) => pi.on(event, handler as never),
+    {
+      activeTools: () => pi.getActiveTools(),
+      consult: registration.consult,
+      ...(dependencies.turnGateDeps ? { deps: dependencies.turnGateDeps } : {}),
+      send: (message) =>
+        pi.sendMessage(message as never, { deliverAs: "steer" } as never),
+      session,
+    }
+  );
 };

package/src/tools/render-advisor-result.ts

@@ -29,6 +29,44 @@ const syncRenderPhase = (context: AdvisorToolContext, phase: string) => {
   context.state.phase = phase;
 };
 
+const attachmentLabels = (details: AdvisorToolDetails | undefined) =>
+  [
+    details?.draftBytes
+      ? `Draft attached · ${details.draftBytes} B`
+      : undefined,
+    details?.preferenceBytes
+      ? `Project preferences attached · ${details.preferenceBytes} B`
+      : undefined,
+    details?.trackedBytes
+      ? `Tracked files attached · ${details.trackedBytes} B`
+      : undefined,
+    details?.untrackedBytes
+      ? `Untracked files attached · ${details.untrackedBytes} B`
+      : undefined,
+  ].filter((label): label is string => label !== undefined);
+
+const renderJevSkipBox = (
+  box: Box,
+  result: AgentToolResult<AdvisorToolDetails>,
+  expanded: boolean,
+  theme: Theme
+) => {
+  const details = advisorResultDetails(result);
+  const lines = [
+    theme.fg("dim", theme.bold("◆ ADVISOR · SKIPPED")),
+    theme.fg("dim", `  ${details?.jev?.reason ?? ""}`),
+  ];
+  box.addChild(new Text(lines.join("\n"), 0, 0));
+  box.addChild(
+    new Markdown(
+      adviceForDisplay(textFrom(result.content), expanded),
+      0,
+      0,
+      getMarkdownTheme()
+    )
+  );
+};
+
 const renderPartialAdvisorResult = (
   box: Box,
   result: AgentToolResult<AdvisorToolDetails>,
@@ -91,6 +129,10 @@ const renderFinalAdvisorResult = (
     context.state.timerId = undefined;
   }
   const details = advisorResultDetails(result);
+  if (details?.jev?.skipped) {
+    renderJevSkipBox(box, result, expanded, theme);
+    return;
+  }
   if (details?.scout) {
     context.state.scout = details.scout;
   }
@@ -112,20 +154,7 @@ const renderFinalAdvisorResult = (
       lines.push(theme.fg("dim", `  Usage: ${usage}`));
     }
   }
-  const attachments = [
-    details?.draftBytes
-      ? `Draft attached · ${details.draftBytes} B`
-      : undefined,
-    details?.preferenceBytes
-      ? `Project preferences attached · ${details.preferenceBytes} B`
-      : undefined,
-    details?.trackedBytes
-      ? `Tracked files attached · ${details.trackedBytes} B`
-      : undefined,
-    details?.untrackedBytes
-      ? `Untracked files attached · ${details.untrackedBytes} B`
-      : undefined,
-  ].filter(Boolean);
+  const attachments = attachmentLabels(details);
   if (attachments.length) {
     lines.push(theme.fg("dim", `  ${attachments.join(" · ")}`));
   }