pi-advisor-flow 0.5.6 → 0.7.0

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

@@ -12,24 +12,25 @@ import {
   advisorScoutEnabledRef,
   getAdvisorMaxCallsPerSession,
   isSimpleMode,
-} from "../config/state.js";
-import { herdrAdvisorActivity } from "../herdr.js";
-import type { AdvisorSessionState } from "../session-state.js";
-import { advisorUsageCost, snapshotAdvisorUsage } from "../usage.js";
-import type { runAdvisorGate } from "./consultation.js";
+} from "../config/state.ts";
+import type { GateFailureMode } from "../config/types.ts";
+import { herdrAdvisorActivity } from "../herdr.ts";
+import type { AdvisorSessionState } from "../session-state.ts";
+import { advisorUsageCost, snapshotAdvisorUsage } from "../usage.ts";
+import type { runAdvisorGate } from "./consultation.ts";
 import {
   blockedDecisionEffect,
   failureEffect,
   gateDecisionEffect,
   gateFailureEffectForMode,
   updateAdvisorUsageStatus,
-} from "./gate-policy.js";
-import { adviceForGateText } from "./gate-protocol.js";
+} from "./gate-policy.ts";
+import { adviceForGateText } from "./gate-protocol.ts";
 import {
   appendScoutLifecycleEntry,
   type ScoutStatusManager,
-} from "./scout-status.js";
-import type { AdvisorGateResult, ScoutToolDetails } from "./types.js";
+} from "./scout-status.ts";
+import type { AdvisorGateResult, ScoutToolDetails } from "./types.ts";
 
 const sendAutomaticGateCall = (pi: ExtensionAPI, event: ToolCallEvent) => {
   pi.sendMessage(
@@ -87,6 +88,65 @@ const sendAutomaticGateResult = (
   );
 };
 
+/** Records the invocation, reports it, and maps the gate decision to its
+ * tool-call result (block reason or proceed). */
+const applyGateDecision = (
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  session: AdvisorSessionState,
+  result: Awaited<ReturnType<typeof runAdvisorGate>>,
+  reason: string,
+  failureMode: GateFailureMode
+): ToolCallEventResult | undefined => {
+  if (!result.ok) {
+    session.recordInvocation({
+      executionEffect: gateFailureEffectForMode(failureMode),
+      failure: result.category,
+      kind: "gate",
+      model: advisorRef,
+      trigger: "repeated-tool-call",
+      usage: result.usage,
+    });
+    updateAdvisorUsageStatus(ctx, session);
+    const failure = failureEffect(
+      result.category,
+      result.message,
+      ctx,
+      session,
+      failureMode
+    );
+    sendAutomaticGateFailure(
+      pi,
+      `**Advisor gate failure (${result.category}):** ${result.message}`,
+      result.usage
+    );
+    return failure.block
+      ? { block: true, reason: `${reason}\n${failure.reason}` }
+      : undefined;
+  }
+  session.recordInvocation({
+    cost: advisorUsageCost(result.usage),
+    decision: result.decision,
+    executionEffect: gateDecisionEffect(result.decision, failureMode),
+    kind: "gate",
+    model: result.model,
+    trigger: result.trigger,
+    usage: result.usage,
+  });
+  updateAdvisorUsageStatus(ctx, session);
+  sendAutomaticGateResult(pi, result);
+  if (result.decision === "proceed") {
+    session.resetRepetition();
+    return;
+  }
+  const gateReason = `Advisor loop review: ${result.markdown}`;
+  if (result.decision === "blocked") {
+    const effect = blockedDecisionEffect(gateReason, ctx, session, failureMode);
+    return effect.block ? { block: true, reason: effect.reason } : undefined;
+  }
+  return { block: true, reason: gateReason };
+};
+
 export const handleAutomaticGate = async (
   pi: ExtensionAPI,
   event: ToolCallEvent,
@@ -120,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");
@@ -151,58 +212,7 @@ export const handleAutomaticGate = async (
       event.toolCallId
     );
     ensureGateCall();
-    if (!result.ok) {
-      session.recordInvocation({
-        executionEffect: gateFailureEffectForMode(failureMode),
-        failure: result.category,
-        kind: "gate",
-        model: advisorRef,
-        trigger: "repeated-tool-call",
-        usage: result.usage,
-      });
-      updateAdvisorUsageStatus(ctx, session);
-      const failure = failureEffect(
-        result.category,
-        result.message,
-        ctx,
-        session,
-        failureMode
-      );
-      sendAutomaticGateFailure(
-        pi,
-        `**Advisor gate failure (${result.category}):** ${result.message}`,
-        result.usage
-      );
-      return failure.block
-        ? { block: true, reason: `${reason}\n${failure.reason}` }
-        : undefined;
-    }
-    session.recordInvocation({
-      cost: advisorUsageCost(result.usage),
-      decision: result.decision,
-      executionEffect: gateDecisionEffect(result.decision, failureMode),
-      kind: "gate",
-      model: result.model,
-      trigger: result.trigger,
-      usage: result.usage,
-    });
-    updateAdvisorUsageStatus(ctx, session);
-    sendAutomaticGateResult(pi, result);
-    if (result.decision === "proceed") {
-      session.resetRepetition();
-      return;
-    }
-    const gateReason = `Advisor loop review: ${result.markdown}`;
-    if (result.decision === "blocked") {
-      const effect = blockedDecisionEffect(
-        gateReason,
-        ctx,
-        session,
-        failureMode
-      );
-      return effect.block ? { block: true, reason: effect.reason } : undefined;
-    }
-    return { block: true, reason: gateReason };
+    return applyGateDecision(pi, ctx, session, result, reason, failureMode);
   } finally {
     scoutStatus.release(ctx, scoutStatusToken);
     herdrAdvisorActivity.finish();

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/prompts.ts

@@ -6,14 +6,14 @@ import {
   advisorPlanGateRef,
   contextMaxCharsRef,
   isSimpleMode,
-} from "../config/state.js";
-import { recentConversation } from "../conversation.js";
+} from "../config/state.ts";
+import { recentConversation } from "../conversation.ts";
 import {
   capRepositoryContext,
   escapeRepositoryText,
   type GitContextLevel,
   type GitContextResult,
-} from "../git.js";
+} from "../git.ts";
 
 export const advisorMessageText = (
   conversation: string,
@@ -47,10 +47,7 @@ export const advisorMessageText = (
   );
 };
 
-/**
- * Splits the character budget so repository context can never starve the
- * conversation: it may claim its own cap or half the budget, whichever is less.
- */
+/** Splits the character budget so repository context can never starve the conversation. */
 export const advisorGitContextBudget = (
   contextMaxChars: number,
   gitContextMaxChars: number

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

@@ -5,35 +5,31 @@ import {
   getAdvisorMaxCallsPerSession,
   getAdvisorSettings,
   isSimpleMode,
-} from "../config/state.js";
-import { herdrAdvisorActivity, notifyHerdrAdvisorFailure } from "../herdr.js";
+} from "../config/state.ts";
+import { herdrAdvisorActivity, notifyHerdrAdvisorFailure } from "../herdr.ts";
 import {
   ADVISOR_STREAM_UPDATE_INTERVAL_MS,
   createCoalescedUpdate,
-} from "../model-stream.js";
+} from "../model-stream.ts";
 import {
   advisorUsageCost,
   advisorUsageForPi,
   snapshotAdvisorUsage,
-} from "../usage.js";
-import { notifyLocalFailure, updateAdvisorUsageStatus } from "./gate-policy.js";
-import { renderAdvisorResult } from "./render-advisor-result.js";
+} 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,
   resolveAdvisorRequest,
-} from "./render-common.js";
-import { scoutDetailsFromEvent } from "./scout-status.js";
+} from "./render-common.ts";
+import { scoutDetailsFromEvent } from "./scout-status.ts";
 import type {
   AdvisorToolContext,
   AdvisorToolDetails,
   ToolRegistrationContext,
-} from "./types.js";
+} from "./types.ts";
 
-/**
- * Validates a tracked-file follow-up and consumes the one-shot handoff only
- * when the call is worth it: consent must be enabled and the session budget
- * was checked by the caller. A rejected call never burns the claim.
- */
 const claimTrackedHandoff = (
   session: ToolRegistrationContext["session"],
   includeTrackedFiles: string[] | undefined
@@ -57,6 +53,7 @@ export const registerAskAdvisorTool = ({
   consult: requestAdvisor,
   pi,
   reservedCalls,
+  screen,
   session,
 }: ToolRegistrationContext): void => {
   pi.registerTool({
@@ -71,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"];
@@ -128,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),
@@ -194,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-lifecycle.ts

@@ -2,13 +2,13 @@ import {
   advisorSessionSummaryRef,
   getAdvisorMaxCallsPerSession,
   isSimpleMode,
-} from "../config/state.js";
-import { loadConfig } from "../config/storage.js";
-import { herdrAdvisorBlock } from "../herdr.js";
-import { reserveAdvisorCall } from "./gate-policy.js";
-import { handleAutomaticGate } from "./loop-gate.js";
-import { advisorInvocationGuidelines } from "./prompts.js";
-import type { ToolRegistrationContext } from "./types.js";
+} from "../config/state.ts";
+import { loadConfig } from "../config/storage.ts";
+import { herdrAdvisorBlock } from "../herdr.ts";
+import { reserveAdvisorCall } from "./gate-policy.ts";
+import { handleAutomaticGate } from "./loop-gate.ts";
+import { advisorInvocationGuidelines } from "./prompts.ts";
+import type { ToolRegistrationContext } from "./types.ts";
 
 export const registerToolLifecycle = ({
   pi,

package/src/tools/register-outcome.ts

@@ -1,10 +1,10 @@
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { advisorOutcomeLoggingRef } from "../config/state.js";
-import { loadConfig } from "../config/storage.js";
-import { textFrom } from "../conversation.js";
-import { ADOPTIONS, VALIDATIONS } from "../outcomes.js";
-import type { ToolRegistrationContext } from "./types.js";
+import { advisorOutcomeLoggingRef } from "../config/state.ts";
+import { loadConfig } from "../config/storage.ts";
+import { textFrom } from "../conversation.ts";
+import { ADOPTIONS, VALIDATIONS } from "../outcomes.ts";
+import type { ToolRegistrationContext } from "./types.ts";
 
 export const registerOutcomeTool = ({
   appendOutcome: appendAdvisorOutcome,

package/src/tools/register-renderers.ts

@@ -3,11 +3,11 @@ import {
   getMarkdownTheme,
 } from "@earendil-works/pi-coding-agent";
 import { Box, Markdown, Text } from "@earendil-works/pi-tui";
-import { getAdvisorSettings } from "../config/state.js";
-import { formatAdvisorUsage } from "../usage.js";
-import { adviceForDisplay, renderAdvisorCallBox } from "./render-common.js";
-import { renderScoutDetails } from "./scout-status.js";
-import type { GateDecision, ScoutToolDetails } from "./types.js";
+import { getAdvisorSettings } from "../config/state.ts";
+import { formatAdvisorUsage } from "../usage.ts";
+import { adviceForDisplay, renderAdvisorCallBox } from "./render-common.ts";
+import { renderScoutDetails } from "./scout-status.ts";
+import type { GateDecision, ScoutToolDetails } from "./types.ts";
 
 export const registerToolRenderers = (pi: ExtensionAPI): void => {
   pi.registerEntryRenderer?.(
@@ -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) => {