pi-advisor-flow 0.6.0 → 0.7.0

package/src/jev/ledger.ts

@@ -0,0 +1,234 @@
+import { formatTokenCount } from "../usage.ts";
+
+export interface AdvisorJevUsageTotals {
+  cost: number;
+  inputTokens: number;
+  outputTokens: number;
+}
+
+export interface AdvisorJevFilterLedger {
+  allowed: number;
+  failures: number;
+  overrides: number;
+  repeatSkipped: number;
+  screened: number;
+  skipped: number;
+}
+
+export interface AdvisorJevGateLedger {
+  checks: number;
+  consultations: number;
+  failures: number;
+  usage: AdvisorJevUsageTotals;
+}
+
+export interface AdvisorJevLedger {
+  filter: AdvisorJevFilterLedger;
+  gate: AdvisorJevGateLedger;
+  usage: AdvisorJevUsageTotals;
+}
+
+export interface AdvisorJevUsage {
+  cost: number;
+  inputTokens: number;
+  outputTokens: number;
+}
+
+export interface JevSkipRecord {
+  normalizedQuestion?: string;
+  turn: number;
+}
+
+/** Invocation fields the Jev summary reads; satisfied by AdvisorInvocationRecord. */
+export interface JevInvocationView {
+  cost?: number;
+  kind: string;
+  trigger: string;
+}
+
+const freshJevUsage = (): AdvisorJevUsageTotals => ({
+  cost: 0,
+  inputTokens: 0,
+  outputTokens: 0,
+});
+
+const freshJevLedger = (): AdvisorJevLedger => ({
+  filter: {
+    allowed: 0,
+    failures: 0,
+    overrides: 0,
+    repeatSkipped: 0,
+    screened: 0,
+    skipped: 0,
+  },
+  gate: { checks: 0, consultations: 0, failures: 0, usage: freshJevUsage() },
+  usage: freshJevUsage(),
+});
+
+const addJevUsage = (totals: AdvisorJevUsageTotals, usage: AdvisorJevUsage) => {
+  totals.cost += usage.cost;
+  totals.inputTokens += usage.inputTokens;
+  totals.outputTokens += usage.outputTokens;
+};
+
+/** One session's Jev screening and turn-gate accounting plus summary lines. */
+export class AdvisorJevLedgerState {
+  #ledger = freshJevLedger();
+  #lastSkip: JevSkipRecord | undefined;
+
+  reset() {
+    this.#ledger = freshJevLedger();
+    this.#lastSkip = undefined;
+  }
+
+  get lastSkip() {
+    return this.#lastSkip;
+  }
+
+  recordFilterAllowed() {
+    this.#ledger.filter.allowed += 1;
+    this.#ledger.filter.screened += 1;
+  }
+
+  recordFilterSkipped(
+    repeat: boolean,
+    normalizedQuestion: string | undefined,
+    turn: number
+  ) {
+    this.#ledger.filter.skipped += 1;
+    this.#ledger.filter.screened += 1;
+    if (repeat) {
+      this.#ledger.filter.repeatSkipped += 1;
+    }
+    this.#lastSkip = {
+      ...(normalizedQuestion ? { normalizedQuestion } : {}),
+      turn,
+    };
+  }
+
+  recordFilterOverride() {
+    this.#ledger.filter.overrides += 1;
+  }
+
+  recordFilterFailure() {
+    this.#ledger.filter.failures += 1;
+  }
+
+  recordFilterUsage(usage: AdvisorJevUsage) {
+    addJevUsage(this.#ledger.usage, usage);
+  }
+
+  recordGateCheck(usage?: AdvisorJevUsage) {
+    this.#ledger.gate.checks += 1;
+    if (usage) {
+      addJevUsage(this.#ledger.gate.usage, usage);
+    }
+  }
+
+  recordGateConsultation() {
+    this.#ledger.gate.consultations += 1;
+  }
+
+  recordGateFailure() {
+    this.#ledger.gate.failures += 1;
+  }
+
+  summaryLines(invocations: readonly JevInvocationView[]): string[] {
+    const lines: string[] = [];
+    const { filter, gate, usage } = this.#ledger;
+    const nonRepeatJevActivity =
+      filter.allowed +
+      (filter.skipped - filter.repeatSkipped) +
+      filter.failures;
+    if (nonRepeatJevActivity === 0 && filter.repeatSkipped > 0) {
+      // Only dedup fired — no Jev call ever happened, so the line must not
+      // claim Jev activity.
+      const parts = [
+        `${filter.repeatSkipped} repeat question${filter.repeatSkipped === 1 ? "" : "s"} skipped, earlier advice reattached`,
+      ];
+      if (filter.overrides > 0) {
+        parts.push(
+          `${filter.overrides} override${filter.overrides === 1 ? "" : "s"}`
+        );
+      }
+      lines.push(`Consultation dedup: ${parts.join(", ")}`);
+      lines.push(
+        this.#savingsLine(this.#markdownCosts(invocations), filter.skipped)
+      );
+    } else if (this.#filterActive()) {
+      lines.push(this.#filterLine(filter));
+      const jevTokens = usage.inputTokens + usage.outputTokens;
+      if (jevTokens > 0) {
+        lines.push(
+          `Jev cost: ${this.#formatJevTokens(usage)} tokens · $${usage.cost.toFixed(4)} (input only; output free)`
+        );
+      }
+      if (filter.skipped > 0) {
+        lines.push(
+          this.#savingsLine(this.#markdownCosts(invocations), filter.skipped)
+        );
+      }
+    }
+    if (gate.checks > 0 || gate.consultations > 0) {
+      lines.push(this.#gateLine(gate, invocations));
+    }
+    return lines;
+  }
+
+  #filterActive() {
+    const { filter } = this.#ledger;
+    return filter.screened > 0 || filter.overrides > 0 || filter.failures > 0;
+  }
+
+  #savingsLine(markdownCosts: number[], skipped: number) {
+    if (markdownCosts.length === 0) {
+      return "Estimated saving from skips: unavailable — no observed consultation cost this session";
+    }
+    const mean =
+      markdownCosts.reduce((sum, cost) => sum + cost, 0) / markdownCosts.length;
+    return `Estimated saving from skips: ≤ $${(mean * skipped).toFixed(4)} — upper bound; assumes each skipped consultation would have cost this session's mean allowed-consultation cost ($${mean.toFixed(4)}), which the skipped calls would likely have undercut`;
+  }
+
+  #gateLine(
+    gate: AdvisorJevGateLedger,
+    invocations: readonly JevInvocationView[]
+  ) {
+    const consultationCosts = invocations
+      .filter(
+        (item): item is JevInvocationView & { cost: number } =>
+          item.trigger === "turn-gate" && typeof item.cost === "number"
+      )
+      .map((item) => item.cost);
+    const gateSpend = consultationCosts.reduce((sum, cost) => sum + cost, 0);
+    return `Turn gate: ${gate.checks} check${gate.checks === 1 ? "" : "s"} (Jev ${this.#formatJevTokens(gate.usage)} · $${gate.usage.cost.toFixed(4)}), ${gate.consultations} consultation${gate.consultations === 1 ? "" : "s"} ($${gateSpend.toFixed(4)})`;
+  }
+
+  #formatJevTokens(usage: AdvisorJevUsageTotals) {
+    return `↑${formatTokenCount(usage.inputTokens + usage.outputTokens)}`;
+  }
+
+  #markdownCosts(invocations: readonly JevInvocationView[]): number[] {
+    return invocations
+      .filter(
+        (item): item is JevInvocationView & { cost: number } =>
+          item.kind === "markdown" && typeof item.cost === "number"
+      )
+      .map((item) => item.cost);
+  }
+
+  #filterLine(filter: AdvisorJevFilterLedger) {
+    const head = `${filter.screened} screened (${filter.allowed} allowed, ${filter.skipped} skipped${filter.repeatSkipped > 0 ? ` [${filter.repeatSkipped} repeat]` : ""})`;
+    const parts = [head];
+    if (filter.overrides > 0) {
+      parts.push(
+        `${filter.overrides} override${filter.overrides === 1 ? "" : "s"}`
+      );
+    }
+    if (filter.failures > 0) {
+      parts.push(
+        `${filter.failures} failure${filter.failures === 1 ? "" : "s"}`
+      );
+    }
+    return `Jev filter: ${parts.join(", ")}`;
+  }
+}

package/src/jev/questions.ts

@@ -0,0 +1,119 @@
+import type { Questions } from "@typesafe-ai/sdk";
+
+/** Exact rubric text for the stakes Score question; level 0 is the skip level. */
+export const STAKES_RUBRIC = [
+  "Negligible: routine, low-risk, mechanical, or reversible; a wrong call costs little and is easy to undo.",
+  "Moderate: some risk or rework, but bounded and recoverable.",
+  "High: material consequences for correctness, security, cost, user trust, or irreversibility.",
+] as const;
+
+const EVIDENCE_RULE =
+  "Judge from `executor_question` and `executor_draft` when present, otherwise from `recent_conversation`; when both are absent, `recent_conversation` is the evidence to judge from.";
+
+export const screeningQuestions: Questions = {
+  self_answerable: {
+    criteria: {
+      false: "The executor needs the Advisor's second opinion.",
+      true: "The executor can resolve this alone with available tools and context.",
+    },
+    instructions: `Can the executor confidently resolve this request alone, using available tools and context? ${EVIDENCE_RULE}`,
+    type: "noul",
+  },
+  stakes: {
+    criteria: [...STAKES_RUBRIC],
+    instructions: `How material are the stakes of the decision behind this consultation request? ${EVIDENCE_RULE}`,
+    type: "score",
+  },
+};
+
+export interface TurnGateQuestions {
+  instructions: string;
+}
+
+export interface ScreeningCriteria {
+  noulMargin: number;
+  skipConfidence: number;
+}
+
+export type ScreeningVerdict = { skip: false } | { skip: true };
+
+const NUMERIC_KEY_PATTERN = /^\d+$/;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+const finiteNumber = (value: unknown): number | undefined =>
+  typeof value === "number" && Number.isFinite(value) ? value : undefined;
+
+/**
+ * Probability mass on the lowest stakes level, resolved through the answer's
+ * legend (the key whose description equals level 0), falling back to the
+ * smallest numeric index key only when no legend resolves. Shape-independent:
+ * never hardcodes a level key and never uses `ceil(score)`.
+ */
+export const lowestStakesProbability = (
+  answer: unknown
+): number | undefined => {
+  if (!isRecord(answer)) {
+    return undefined;
+  }
+  const probabilities = isRecord(answer.probabilities)
+    ? answer.probabilities
+    : {};
+  const legend = isRecord(answer.legend) ? answer.legend : undefined;
+  if (legend) {
+    const exact = Object.keys(legend).find(
+      (key) => legend[key] === STAKES_RUBRIC[0]
+    );
+    if (exact) {
+      return finiteNumber(probabilities[exact]);
+    }
+  }
+  const numericKeys = Object.keys(probabilities).filter((key) =>
+    NUMERIC_KEY_PATTERN.test(key)
+  );
+  if (numericKeys.length === 0) {
+    return undefined;
+  }
+  const lowest = numericKeys.reduce((left, right) =>
+    Number(left) <= Number(right) ? left : right
+  );
+  return finiteNumber(probabilities[lowest]);
+};
+
+const selfAnswerableNoul = (answer: unknown): number | undefined =>
+  isRecord(answer) ? finiteNumber(answer.noul) : undefined;
+
+/** Pure composition: skip requires the hard conjunction of confident
+ * negligible stakes AND confident self-answerability. Any missing, NaN, or
+ * malformed input allows. Never a weighted sum. */
+export const composeScreeningVerdict = (
+  answers: unknown,
+  { noulMargin, skipConfidence }: ScreeningCriteria
+): ScreeningVerdict => {
+  if (!isRecord(answers)) {
+    return { skip: false };
+  }
+  const negligibleMass = lowestStakesProbability(answers.stakes);
+  const noul = selfAnswerableNoul(answers.self_answerable);
+  if (negligibleMass === undefined || noul === undefined) {
+    return { skip: false };
+  }
+  const confidentlySelfAnswerable = noul >= 0.5 + noulMargin;
+  return {
+    skip: negligibleMass >= skipConfidence && confidentlySelfAnswerable,
+  };
+};
+
+/** Confident-true only; any uncertainty means no invocation. */
+export const composeTurnGateVerdict = (
+  answers: unknown,
+  threshold: number
+): boolean => {
+  if (!isRecord(answers)) {
+    return false;
+  }
+  const answer = answers.should_consult;
+  const noul = isRecord(answer) ? finiteNumber(answer.noul) : undefined;
+  return noul !== undefined && noul >= threshold;
+};

package/src/jev/state.ts

@@ -0,0 +1,47 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { JsonValue } from "@typesafe-ai/sdk";
+import {
+  advisorJevDigestMaxCharsRef,
+  advisorRedactSecretsRef,
+} from "../config/state.ts";
+import { recentConversation } from "../conversation.ts";
+import { redactAndCapText } from "../redaction.ts";
+
+/** Per-field byte cap for executor question and draft sent to Jev. */
+export const JEV_TEXT_CAP_BYTES = 8 * 1024;
+
+export interface JevStateInput {
+  draft?: string;
+  question?: string;
+}
+
+export type JevState = Record<string, JsonValue>;
+
+/** Builds the Jev screening state: named fields, redacted and capped through
+ * the existing egress pipeline, with the conversation digest as fallback
+ * evidence when no explicit request exists. */
+export const buildJevState = (
+  ctx: ExtensionContext,
+  input: JevStateInput = {}
+): JevState => {
+  const state: JevState = { role: "executor" };
+  if (input.question) {
+    state.executor_question = redactAndCapText(
+      input.question,
+      JEV_TEXT_CAP_BYTES,
+      advisorRedactSecretsRef
+    );
+  }
+  if (input.draft) {
+    state.executor_draft = redactAndCapText(
+      input.draft,
+      JEV_TEXT_CAP_BYTES,
+      advisorRedactSecretsRef
+    );
+  }
+  const digest = recentConversation(ctx, advisorJevDigestMaxCharsRef);
+  if (digest) {
+    state.recent_conversation = digest;
+  }
+  return state;
+};

package/src/jev/transport.ts

@@ -0,0 +1,58 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { advisorJevTransportRef } from "../config/state.ts";
+import { type JevKeySource, resolveTypeSafeKey } from "./key-store.ts";
+
+export type JevTransportKind = "typesafe" | "openrouter";
+
+export interface JevCredentials {
+  apiKey: string;
+  /** Where the TypeSafe key came from; present on the typesafe transport. */
+  source?: JevKeySource;
+  transport: JevTransportKind;
+}
+
+export interface JevTransportDeps {
+  /** Reads a pi-stored provider login; injectable for tests. */
+  getProviderKey?: (provider: string) => Promise<string | undefined>;
+  /** Resolves the TypeSafe key chain; injectable for tests. */
+  resolveTypesafe?: () => ReturnType<typeof resolveTypeSafeKey>;
+}
+
+const OPENROUTER_PROVIDER = "openrouter";
+
+const openRouterKey = async (
+  ctx: ExtensionContext | undefined,
+  deps: JevTransportDeps
+): Promise<string | undefined> => {
+  const key = deps.getProviderKey
+    ? await deps.getProviderKey(OPENROUTER_PROVIDER)
+    : await ctx?.modelRegistry?.getApiKeyForProvider(OPENROUTER_PROVIDER);
+  return key?.trim() || undefined;
+};
+
+/** Resolves how Jev calls authenticate: a dedicated TypeSafe key first, then
+ * the existing pi OpenRouter login (reuse per advisorJevTransport). */
+export const resolveJevTransport = async (
+  ctx?: ExtensionContext,
+  deps: JevTransportDeps = {}
+): Promise<JevCredentials | undefined> => {
+  const preference = advisorJevTransportRef;
+  if (preference !== "openrouter") {
+    const resolveTypesafe = deps.resolveTypesafe ?? resolveTypeSafeKey;
+    const resolution = await resolveTypesafe();
+    if (resolution.key) {
+      return {
+        apiKey: resolution.key,
+        ...(resolution.source ? { source: resolution.source } : {}),
+        transport: "typesafe",
+      };
+    }
+  }
+  if (preference === "typesafe") {
+    return undefined;
+  }
+  const openrouter = await openRouterKey(ctx, deps);
+  return openrouter
+    ? { apiKey: openrouter, transport: "openrouter" }
+    : undefined;
+};

package/src/outcomes.ts

@@ -15,7 +15,11 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 export type OutcomeAdoption = "followed" | "not-followed" | "unknown";
 export type OutcomeValidation = "passed" | "failed" | "not-run" | "unknown";
-type OutcomeTrigger = "manual" | "executor-requested" | "repeated-tool-call";
+type OutcomeTrigger =
+  | "manual"
+  | "executor-requested"
+  | "turn-gate"
+  | "repeated-tool-call";
 export const ADOPTIONS: OutcomeAdoption[] = [
   "followed",
   "not-followed",

package/src/session-state.ts

@@ -1,3 +1,4 @@
+import { AdvisorJevLedgerState, type AdvisorJevUsage } from "./jev/ledger.ts";
 import {
   type AdvisorUsageTotals,
   addAdvisorUsage,
@@ -7,7 +8,7 @@ import {
 } from "./usage.ts";
 
 export type GateDecision = "proceed" | "revise" | "blocked";
-export type ConsultationTrigger = "manual" | "executor-requested";
+export type ConsultationTrigger = "manual" | "executor-requested" | "turn-gate";
 export type GateTrigger =
   | "repeated-tool-call"
   | "completion-review"
@@ -121,7 +122,14 @@ interface RepetitionState {
 
 interface AdviceLedger {
   draftConsultations: number;
-  issued: Map<string, { advice: string; trigger: ConsultationTrigger }>;
+  issued: Map<
+    string,
+    {
+      advice: string;
+      normalizedQuestion?: string;
+      trigger: ConsultationTrigger;
+    }
+  >;
   lastAdvice?: string;
   outcomes: number;
   pending: Set<string>;
@@ -155,6 +163,9 @@ export class AdvisorSessionState {
   #ledger = freshAdviceLedger();
   #usage = freshUsage();
   #consumedCalls = 0;
+  readonly #jev = new AdvisorJevLedgerState();
+  #sessionTurnOrdinal = 0;
+  #turnsSinceConsultation = 0;
 
   resetTask() {
     this.#repetition = freshRepetition();
@@ -162,6 +173,9 @@ export class AdvisorSessionState {
     this.#ledger = freshAdviceLedger();
     this.#usage = freshUsage();
     this.#consumedCalls = 0;
+    this.#jev.reset();
+    this.#sessionTurnOrdinal = 0;
+    this.#turnsSinceConsultation = 0;
   }
 
   clearBlocked() {
@@ -214,6 +228,26 @@ export class AdvisorSessionState {
     return this.#consumedCalls;
   }
 
+  /** Counts one completed executor turn on both turn counters. The ordinal
+   * feeds the filter override window and summary positions and is never reset
+   * by anything; turnsSinceConsultation resets on every consultation. */
+  recordCompletedTurn() {
+    this.#sessionTurnOrdinal += 1;
+    this.#turnsSinceConsultation += 1;
+  }
+
+  resetTurnsSinceConsultation() {
+    this.#turnsSinceConsultation = 0;
+  }
+
+  get sessionTurnOrdinal() {
+    return this.#sessionTurnOrdinal;
+  }
+
+  get turnsSinceConsultation() {
+    return this.#turnsSinceConsultation;
+  }
+
   /** Returns a copy of cumulative direct Advisor usage for this session. */
   get usageTotals(): AdvisorUsageTotals {
     return { ...this.#usage.totals };
@@ -232,14 +266,34 @@ export class AdvisorSessionState {
     id: string,
     advice: string,
     trigger: ConsultationTrigger,
-    draft = false
+    draft = false,
+    normalizedQuestion?: string
   ) {
-    this.#ledger.issued.set(id, { advice, trigger });
+    this.#ledger.issued.set(id, {
+      advice,
+      ...(normalizedQuestion ? { normalizedQuestion } : {}),
+      trigger,
+    });
     this.#ledger.lastAdvice = advice;
     if (draft) {
       this.#ledger.draftConsultations += 1;
     }
   }
+
+  /** Returns earlier advice for an exactly-matching normalized question. */
+  reattachedAdviceFor(
+    normalizedQuestion: string | undefined
+  ): string | undefined {
+    if (!normalizedQuestion) {
+      return undefined;
+    }
+    for (const entry of this.#ledger.issued.values()) {
+      if (entry.normalizedQuestion === normalizedQuestion) {
+        return entry.advice;
+      }
+    }
+    return undefined;
+  }
   claimTrackedFiles(paths: string[]) {
     const advice = this.#ledger.lastAdvice;
     if (!advice || paths.length === 0) {
@@ -324,6 +378,7 @@ export class AdvisorSessionState {
       [
         "manual",
         "executor-requested",
+        "turn-gate",
         "repeated-tool-call",
         "completion-review",
         "custom-rule",
@@ -333,9 +388,47 @@ export class AdvisorSessionState {
     );
   }
 
+  recordJevFilterAllowed() {
+    this.#jev.recordFilterAllowed();
+  }
+  recordJevFilterSkipped(repeat: boolean, normalizedQuestion?: string) {
+    this.#jev.recordFilterSkipped(
+      repeat,
+      normalizedQuestion,
+      this.#sessionTurnOrdinal
+    );
+  }
+  get lastJevSkip() {
+    return this.#jev.lastSkip;
+  }
+  recordJevFilterOverride() {
+    this.#jev.recordFilterOverride();
+  }
+  recordJevFilterFailure() {
+    this.#jev.recordFilterFailure();
+  }
+  recordJevFilterUsage(usage: AdvisorJevUsage) {
+    this.#jev.recordFilterUsage(usage);
+  }
+
+  recordJevGateCheck(usage?: AdvisorJevUsage) {
+    this.#jev.recordGateCheck(usage);
+  }
+  recordJevGateConsultation() {
+    this.#jev.recordGateConsultation();
+  }
+  recordJevGateFailure() {
+    this.#jev.recordGateFailure();
+  }
+
   summary(limit: number | undefined) {
     const { invocations, totals } = this.#usage;
-    if (invocations.length === 0 && this.#repetition.interventions === 0) {
+    const jevLines = this.#jev.summaryLines(invocations);
+    if (
+      invocations.length === 0 &&
+      this.#repetition.interventions === 0 &&
+      jevLines.length === 0
+    ) {
       return;
     }
     const markdown = invocations.filter((item) => item.kind === "markdown");
@@ -366,6 +459,7 @@ export class AdvisorSessionState {
       `Loop matching: normalized tool signatures; ${this.#repetition.interventions} gate intervention${this.#repetition.interventions === 1 ? "" : "s"}`,
       `Execution effects: ${effects("tool-blocked")} tool blocked, ${effects("session-blocked")} sessions blocked, ${effects("continued")} continued`,
       `Failures: ${failures.length ? failures.join(", ") : "none"}`,
+      ...jevLines,
     ].join("\n");
   }
 }