pi-advisor-flow 0.5.6 → 0.7.0

package/src/session-state.ts

@@ -1,19 +1,20 @@
+import { AdvisorJevLedgerState, type AdvisorJevUsage } from "./jev/ledger.ts";
 import {
   type AdvisorUsageTotals,
   addAdvisorUsage,
   emptyAdvisorUsageTotals,
   formatAdvisorUsageStatus,
   formatAdvisorUsageTotals,
-} from "./usage.js";
+} 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"
   | "custom-rule";
-export type AdvisorTrigger = ConsultationTrigger | GateTrigger;
-export type ExecutionEffect = "continued" | "tool-blocked" | "session-blocked";
+type AdvisorTrigger = ConsultationTrigger | GateTrigger;
+type ExecutionEffect = "continued" | "tool-blocked" | "session-blocked";
 
 export interface AdvisorInvocationRecord {
   cost?: number;
@@ -113,46 +114,77 @@ export const normalizeToolInput = (
 export const normalizedToolSignature = (toolName: string, input: unknown) =>
   `${toolName}:${JSON.stringify(normalizeToolInput(toolName, input))}`;
 
+interface RepetitionState {
+  count: number;
+  interventions: number;
+  previousSignature?: string;
+}
+
+interface AdviceLedger {
+  draftConsultations: number;
+  issued: Map<
+    string,
+    {
+      advice: string;
+      normalizedQuestion?: string;
+      trigger: ConsultationTrigger;
+    }
+  >;
+  lastAdvice?: string;
+  outcomes: number;
+  pending: Set<string>;
+  reported: Set<string>;
+}
+
+interface UsageState {
+  invocations: AdvisorInvocationRecord[];
+  totals: AdvisorUsageTotals;
+}
+
+const freshRepetition = (): RepetitionState => ({
+  count: 0,
+  interventions: 0,
+});
+const freshAdviceLedger = (): AdviceLedger => ({
+  draftConsultations: 0,
+  issued: new Map(),
+  outcomes: 0,
+  pending: new Set(),
+  reported: new Set(),
+});
+const freshUsage = (): UsageState => ({
+  invocations: [],
+  totals: emptyAdvisorUsageTotals(),
+});
+
 export class AdvisorSessionState {
-  #previousSignature?: string;
-  #repetitions = 0;
+  #repetition = freshRepetition();
   #blockedReason?: string;
-  #invocations: AdvisorInvocationRecord[] = [];
-  #loopInterventions = 0;
+  #ledger = freshAdviceLedger();
+  #usage = freshUsage();
   #consumedCalls = 0;
-  readonly #issuedAdvice = new Map<
-    string,
-    { advice: string; trigger: ConsultationTrigger }
-  >();
-  readonly #pendingAdvice = new Set<string>();
-  readonly #reportedAdvice = new Set<string>();
-  #draftConsultations = 0;
-  #outcomes = 0;
-  #lastAdvice?: string;
-  #usage = emptyAdvisorUsageTotals();
+  readonly #jev = new AdvisorJevLedgerState();
+  #sessionTurnOrdinal = 0;
+  #turnsSinceConsultation = 0;
 
   resetTask() {
-    this.#previousSignature = undefined;
-    this.#repetitions = 0;
+    this.#repetition = freshRepetition();
     this.#blockedReason = undefined;
-    this.#invocations = [];
-    this.#loopInterventions = 0;
+    this.#ledger = freshAdviceLedger();
+    this.#usage = freshUsage();
     this.#consumedCalls = 0;
-    this.#issuedAdvice.clear();
-    this.#pendingAdvice.clear();
-    this.#reportedAdvice.clear();
-    this.#draftConsultations = 0;
-    this.#outcomes = 0;
-    this.#lastAdvice = undefined;
-    this.#usage = emptyAdvisorUsageTotals();
+    this.#jev.reset();
+    this.#sessionTurnOrdinal = 0;
+    this.#turnsSinceConsultation = 0;
   }
 
   clearBlocked() {
     this.#blockedReason = undefined;
   }
   resetRepetition() {
-    this.#previousSignature = undefined;
-    this.#repetitions = 0;
+    // Cumulative interventions feed the session summary and must survive this reset.
+    this.#repetition.count = 0;
+    this.#repetition.previousSignature = undefined;
   }
   get blocked() {
     return this.#blockedReason !== undefined;
@@ -169,13 +201,15 @@ export class AdvisorSessionState {
       return false;
     }
     const signature = normalizedToolSignature(toolName, input);
-    this.#repetitions =
-      signature === this.#previousSignature ? this.#repetitions + 1 : 1;
-    this.#previousSignature = signature;
-    if (this.#repetitions < threshold) {
+    this.#repetition.count =
+      signature === this.#repetition.previousSignature
+        ? this.#repetition.count + 1
+        : 1;
+    this.#repetition.previousSignature = signature;
+    if (this.#repetition.count < threshold) {
       return false;
     }
-    this.#loopInterventions += 1;
+    this.#repetition.interventions += 1;
     return true;
   }
 
@@ -194,34 +228,75 @@ 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 };
+    return { ...this.#usage.totals };
   }
 
   /** Returns the footer-ready direct Advisor usage status for this session. */
   usageStatus() {
-    return formatAdvisorUsageStatus(this.#usage);
+    return formatAdvisorUsageStatus(this.#usage.totals);
   }
 
   recordInvocation(record: AdvisorInvocationRecord) {
-    this.#invocations.push(record);
-    addAdvisorUsage(this.#usage, record.usage);
+    this.#usage.invocations.push(record);
+    addAdvisorUsage(this.#usage.totals, record.usage);
   }
   issueAdvice(
     id: string,
     advice: string,
     trigger: ConsultationTrigger,
-    draft = false
+    draft = false,
+    normalizedQuestion?: string
   ) {
-    this.#issuedAdvice.set(id, { advice, trigger });
-    this.#lastAdvice = advice;
+    this.#ledger.issued.set(id, {
+      advice,
+      ...(normalizedQuestion ? { normalizedQuestion } : {}),
+      trigger,
+    });
+    this.#ledger.lastAdvice = advice;
     if (draft) {
-      this.#draftConsultations += 1;
+      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[]) {
-    if (!this.#lastAdvice || paths.length === 0) {
+    const advice = this.#ledger.lastAdvice;
+    if (!advice || paths.length === 0) {
       return false;
     }
     const mentioned = paths.every((path) => {
@@ -230,38 +305,38 @@ export class AdvisorSessionState {
         "(^|[\\s\\\"'`()\\[])" +
         escaped +
         "(?=$|[\\s\\\"'`),;:!?\\]]|\\.(?=\\s|$))";
-      return new RegExp(boundary).test(this.#lastAdvice as string);
+      return new RegExp(boundary).test(advice);
     });
     if (!mentioned) {
       return false;
     }
-    this.#lastAdvice = undefined;
+    this.#ledger.lastAdvice = undefined;
     return true;
   }
 
   reserveAdvice(id: string) {
-    if (this.#reportedAdvice.has(id) || this.#pendingAdvice.has(id)) {
+    if (this.#ledger.reported.has(id) || this.#ledger.pending.has(id)) {
       return;
     }
-    const advice = this.#issuedAdvice.get(id);
+    const advice = this.#ledger.issued.get(id);
     if (!advice) {
       return;
     }
-    this.#pendingAdvice.add(id);
+    this.#ledger.pending.add(id);
     return advice;
   }
 
   commitAdvice(id: string) {
-    if (!this.#pendingAdvice.delete(id)) {
+    if (!this.#ledger.pending.delete(id)) {
       return false;
     }
-    this.#reportedAdvice.add(id);
-    this.#outcomes += 1;
+    this.#ledger.reported.add(id);
+    this.#ledger.outcomes += 1;
     return true;
   }
 
   releaseAdvice(id: string) {
-    this.#pendingAdvice.delete(id);
+    this.#ledger.pending.delete(id);
   }
 
   /** Compatibility helper for synchronous callers that can commit immediately. */
@@ -274,17 +349,11 @@ export class AdvisorSessionState {
     return advice;
   }
 
-  summary(limit: number | undefined) {
-    if (this.#invocations.length === 0 && this.#loopInterventions === 0) {
-      return;
-    }
-    const markdown = this.#invocations.filter(
-      (item) => item.kind === "markdown"
+  #decisionsLine() {
+    const gates = this.#usage.invocations.filter(
+      (item) => item.kind === "gate"
     );
-    const gates = this.#invocations.filter((item) => item.kind === "gate");
-    const countTrigger = (trigger: AdvisorTrigger) =>
-      this.#invocations.filter((item) => item.trigger === trigger).length;
-    const decisions =
+    return (
       (["proceed", "revise", "blocked"] as GateDecision[])
         .map(
           (decision) =>
@@ -295,34 +364,102 @@ export class AdvisorSessionState {
         )
         .filter(([, count]) => count > 0)
         .map(([decision, count]) => `${count} ${decision}`)
-        .join(", ") || "none";
+        .join(", ") || "none"
+    );
+  }
+
+  #countTrigger(trigger: AdvisorTrigger) {
+    return this.#usage.invocations.filter((item) => item.trigger === trigger)
+      .length;
+  }
+
+  #triggersLine() {
+    return (
+      [
+        "manual",
+        "executor-requested",
+        "turn-gate",
+        "repeated-tool-call",
+        "completion-review",
+        "custom-rule",
+      ]
+        .filter((trigger) => this.#countTrigger(trigger as AdvisorTrigger) > 0)
+        .join(", ") || "none"
+    );
+  }
+
+  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;
+    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");
+    const gates = invocations.filter((item) => item.kind === "gate");
     const effects = (effect: ExecutionEffect) =>
-      this.#invocations.filter((item) => item.executionEffect === effect)
-        .length;
-    const failures = this.#invocations
+      invocations.filter((item) => item.executionEffect === effect).length;
+    const failures = invocations
       .filter((item) => item.failure)
       .map((item) => item.failure);
     const models =
-      [
-        ...new Set(this.#invocations.map((item) => item.model).filter(Boolean)),
-      ].join(", ") || "unknown";
+      [...new Set(invocations.map((item) => item.model).filter(Boolean))].join(
+        ", "
+      ) || "unknown";
     const budget =
       limit === undefined
         ? `${this.#consumedCalls} used; unlimited remaining`
         : `${this.#consumedCalls} / ${limit} used; ${Math.max(0, limit - this.#consumedCalls)} remaining`;
     return [
       "[Session Advisor Summary]",
-      `Consultations: ${markdown.length} Markdown (${countTrigger("manual")} manual, ${countTrigger("executor-requested")} executor-requested), automatic gates: ${gates.length}`,
-      `Triggers: ${["manual", "executor-requested", "repeated-tool-call", "completion-review", "custom-rule"].filter((trigger) => countTrigger(trigger as AdvisorTrigger) > 0).join(", ") || "none"}`,
+      `Consultations: ${markdown.length} Markdown (${this.#countTrigger("manual")} manual, ${this.#countTrigger("executor-requested")} executor-requested), automatic gates: ${gates.length}`,
+      `Triggers: ${this.#triggersLine()}`,
       `Models: ${models}`,
       `Budget: ${budget}`,
-      `Usage: ${formatAdvisorUsageTotals(this.#usage)}`,
-      `Markdown advice: ${markdown.length} responses (${this.#draftConsultations} with drafts)`,
-      `Outcome reports: ${this.#outcomes}`,
-      `Gate decisions: ${decisions}`,
-      `Loop matching: normalized tool signatures; ${this.#loopInterventions} gate intervention${this.#loopInterventions === 1 ? "" : "s"}`,
+      `Usage: ${formatAdvisorUsageTotals(totals)}`,
+      `Markdown advice: ${markdown.length} responses (${this.#ledger.draftConsultations} with drafts)`,
+      `Outcome reports: ${this.#ledger.outcomes}`,
+      `Gate decisions: ${this.#decisionsLine()}`,
+      `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");
   }
 }

package/src/tool-result-cap.ts

@@ -0,0 +1,88 @@
+import {
+  DEFAULT_ADVISOR_TOOL_RESULT_MAX_BYTES,
+  DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES,
+} from "./config/types.ts";
+import { byteLength, capUtf8Bytes } from "./content-utils.ts";
+
+export interface ToolResultTruncation {
+  content: string;
+  omittedLines: number;
+  totalBytes: number;
+  totalLines: number;
+  truncated: boolean;
+}
+
+const OMITTED_MARKER = "[... omitted tool-result section ...]";
+
+export const capToolResult = (
+  value: string,
+  maxLines = DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES,
+  maxBytes = DEFAULT_ADVISOR_TOOL_RESULT_MAX_BYTES
+): ToolResultTruncation => {
+  const lines = value.split("\n");
+  const totalLines = lines.length;
+  const totalBytes = byteLength(value);
+  if ((maxLines === 0 || maxBytes === 0) && value.length > 0) {
+    return {
+      content: "[Tool result omitted: configured limit is zero]",
+      omittedLines: totalLines,
+      totalBytes,
+      totalLines,
+      truncated: true,
+    };
+  }
+  if (totalLines <= maxLines && totalBytes <= maxBytes) {
+    return {
+      content: value,
+      omittedLines: 0,
+      totalBytes,
+      totalLines,
+      truncated: false,
+    };
+  }
+
+  const markerBytes = byteLength(OMITTED_MARKER);
+  if (maxBytes < markerBytes || maxLines === 1) {
+    return {
+      content: capUtf8Bytes(OMITTED_MARKER, maxBytes),
+      omittedLines: totalLines,
+      totalBytes,
+      totalLines,
+      truncated: true,
+    };
+  }
+  const headCount = Math.floor((maxLines - 1) / 2);
+  const tailCount = maxLines - 1 - headCount;
+  const collect = (
+    candidates: string[],
+    maxEntries: number,
+    maxContentBytes: number
+  ) => {
+    const selected: string[] = [];
+    let used = 0;
+    for (const line of candidates.slice(0, maxEntries)) {
+      const next = used + byteLength(line) + (selected.length ? 1 : 0);
+      if (next > maxContentBytes) {
+        break;
+      }
+      selected.push(line);
+      used = next;
+    }
+    return selected;
+  };
+  const availableBytes = maxBytes - markerBytes - 2;
+  const head = collect(lines, headCount, Math.floor(availableBytes / 2));
+  const tail = collect(
+    lines.slice(Math.max(head.length, lines.length - tailCount)),
+    tailCount,
+    availableBytes - byteLength(head.join("\n"))
+  );
+  const content = [...head, OMITTED_MARKER, ...tail].join("\n");
+  return {
+    content,
+    omittedLines: Math.max(0, totalLines - head.length - tail.length),
+    totalBytes,
+    totalLines,
+    truncated: true,
+  };
+};

package/src/tools/consult-context.ts

@@ -0,0 +1,155 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  readTrackedFiles,
+  readUntrackedFiles,
+  type UntrackedAttachment,
+} from "../attachments.ts";
+import {
+  advisorGitContextMaxCharsRef,
+  advisorGitContextRef,
+  advisorRedactSecretsRef,
+  advisorScoutEnabledRef,
+  advisorTrackedFileContentRef,
+  advisorUntrackedContentRef,
+  contextMaxCharsRef,
+} from "../config/state.ts";
+import {
+  clampGitContextLevel,
+  collectGitContext,
+  type GitContextLevel,
+} from "../git.ts";
+import { readProjectPreferences } from "../preferences.ts";
+import { redactAndCapText, redactSecrets } from "../redaction.ts";
+import {
+  runAdvisorScout,
+  type ScoutLifecycleEvent,
+  type ScoutOutcome,
+} from "../scout.ts";
+import { curateAdvisorConversation } from "../scout-curation.ts";
+import {
+  advisorGitContextBudget,
+  advisorRepositoryContext,
+  advisorRequestConversation,
+} from "./prompts.ts";
+
+/** Maximum bytes for project preferences and the redacted draft. */
+const ATTACHMENT_TEXT_MAX_BYTES = 8 * 1024;
+/** Combined budget for untracked plus tracked file attachments. */
+const ATTACHMENTS_TOTAL_MAX_BYTES = 24 * 1024;
+
+export interface ConsultationContextOptions {
+  ctx: ExtensionContext;
+  currentInvocationId?: string;
+  draft?: string;
+  gitContext?: GitContextLevel;
+  includeTracked?: string[];
+  includeUntracked?: string[];
+  onScout?: (event: ScoutLifecycleEvent) => void;
+  signal?: AbortSignal;
+}
+
+export interface ConsultationContext {
+  /** Disclosed repository changes header. */
+  changeText: string;
+  /** Curated (or legacy) conversation body. */
+  conversation: string;
+  /** Redacted draft text, if a draft was supplied. */
+  draftText?: string;
+  /** Redacted project preferences, if present. */
+  preferences?: { bytes: number; text: string };
+  /** Non-cancelling Scout outcome, when Scout ran. */
+  scout?: Exclude<ScoutOutcome, { cancelled: true }>;
+  /** Redacted tracked-file attachments. */
+  tracked: UntrackedAttachment[];
+  /** Redacted untracked-file attachments. */
+  untracked: UntrackedAttachment[];
+}
+
+/** Assembles every context region the Advisor request embeds: repository
+ * changes (spending the shared budget first), the curated conversation,
+ * project preferences, and consented file attachments. */
+export const assembleConsultationContext = async (
+  options: ConsultationContextOptions
+): Promise<ConsultationContext> => {
+  const { ctx } = options;
+
+  // The user setting is the ceiling; the Executor may only narrow it.
+  const allowed = advisorGitContextRef;
+  const level = clampGitContextLevel(options.gitContext ?? allowed, allowed);
+  const gitBudget = advisorGitContextBudget(
+    contextMaxCharsRef,
+    advisorGitContextMaxCharsRef
+  );
+  const changes = collectGitContext(
+    ctx.cwd,
+    level,
+    gitBudget,
+    advisorRedactSecretsRef ? redactSecrets : undefined
+  );
+  // 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,
+    options.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,
+    options.signal,
+    options.onScout,
+    advisorScoutEnabledRef,
+    runAdvisorScout,
+    options.currentInvocationId,
+    conversationBudget
+  );
+  const preferences = await readProjectPreferences(
+    ctx,
+    ATTACHMENT_TEXT_MAX_BYTES,
+    advisorRedactSecretsRef
+  );
+  const draftText = options.draft
+    ? redactAndCapText(
+        options.draft,
+        ATTACHMENT_TEXT_MAX_BYTES,
+        advisorRedactSecretsRef
+      )
+    : undefined;
+  const untracked = await readUntrackedFiles(
+    ctx.cwd,
+    options.includeUntracked ?? [],
+    advisorUntrackedContentRef,
+    advisorRedactSecretsRef
+  );
+  const tracked = await readTrackedFiles(
+    ctx.cwd,
+    options.includeTracked ?? [],
+    advisorTrackedFileContentRef,
+    advisorRedactSecretsRef,
+    Math.max(
+      0,
+      ATTACHMENTS_TOTAL_MAX_BYTES -
+        untracked.reduce((sum, item) => sum + item.bytes, 0)
+    )
+  );
+  return {
+    changeText,
+    conversation: curated.conversation,
+    draftText,
+    preferences,
+    scout: curated.scout,
+    tracked,
+    untracked,
+  };
+};