pi-advisor-flow 0.3.6 → 0.5.0

package/src/config.ts

@@ -13,8 +13,8 @@ import {
   isValidGitContextLevel,
 } from "./git.js";
 
-export const FALLBACK_EXECUTOR = "aikeys/claude-sonnet-5";
-export const FALLBACK_ADVISOR = "aikeys/claude-fable-5";
+export const FALLBACK_EXECUTOR = "openai-codex/gpt-5.6-luna";
+export const FALLBACK_ADVISOR = "openai-codex/gpt-5.6-sol";
 export const DEFAULT_CONTEXT_MAX_CHARS = 15_000;
 export const MAX_CONTEXT_MAX_CHARS = Number.MAX_SAFE_INTEGER;
 export const DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES = DEFAULT_MAX_LINES;
@@ -66,6 +66,8 @@ export let advisorOutcomeLoggingRef = false;
 export let advisorUntrackedContentRef = false;
 export let advisorTrackedFileContentRef = false;
 export let advisorScoutEnabledRef = false;
+export let showUsageDetailsRef = true;
+export let showUsageFooterRef = false;
 
 export const setExecutorRef = (ref: string) => {
   executorRef = ref;
@@ -174,6 +176,12 @@ export const setAdvisorTrackedFileContentRef = (enabled: boolean) => {
 export const setAdvisorScoutEnabledRef = (enabled: boolean) => {
   advisorScoutEnabledRef = enabled;
 };
+export const setShowUsageDetailsRef = (enabled: boolean) => {
+  showUsageDetailsRef = enabled;
+};
+export const setShowUsageFooterRef = (enabled: boolean) => {
+  showUsageFooterRef = enabled;
+};
 
 /**
  * Returns the current live settings state. Use this at UI boundaries instead of
@@ -200,6 +208,8 @@ export const getAdvisorSettings = () => ({
   redactSecrets: advisorRedactSecretsRef,
   scoutEnabled: advisorScoutEnabledRef,
   sessionSummary: advisorSessionSummaryRef,
+  showUsageDetails: showUsageDetailsRef,
+  showUsageFooter: showUsageFooterRef,
   simpleMode: simpleModeRef,
   toolPolicies: { ...advisorToolPoliciesRef },
   toolResultMaxBytes: advisorToolResultMaxBytesRef,
@@ -208,9 +218,13 @@ export const getAdvisorSettings = () => ({
   untrackedContent: advisorUntrackedContentRef,
 });
 
+/** Reads the live session budget at each enforcement boundary. */
+export const getAdvisorMaxCallsPerSession = () =>
+  getAdvisorSettings().maxCallsPerSession;
+
 export const splitRef = (ref: string): [string, string] => {
   const i = ref.indexOf("/");
-  return i === -1 ? ["aikeys", ref] : [ref.slice(0, i), ref.slice(i + 1)];
+  return i === -1 ? ["openai-codex", ref] : [ref.slice(0, i), ref.slice(i + 1)];
 };
 
 export const configPaths = (ctx: ExtensionContext) => [
@@ -249,6 +263,8 @@ export interface AdvisorConfig {
   executor?: string;
   executorEffort?: string;
   gateFailureMode?: GateFailureMode;
+  showUsageDetails?: boolean;
+  showUsageFooter?: boolean;
   simpleMode?: boolean;
 }
 
@@ -269,6 +285,7 @@ const CONFIG_KEYS = new Set<keyof AdvisorConfig>([
   "advisorPlanGate",
   "advisorSessionSummary",
   "advisorScoutEnabled",
+  "showUsageDetails",
   "simpleMode",
   "alwaysOn",
   "advisorToolResultMaxBytes",
@@ -282,6 +299,7 @@ const CONFIG_KEYS = new Set<keyof AdvisorConfig>([
   "executor",
   "executorEffort",
   "gateFailureMode",
+  "showUsageFooter",
 ]);
 const BOOLEAN_CONFIG_KEYS = [
   "advisorPlanGate",
@@ -292,6 +310,8 @@ const BOOLEAN_CONFIG_KEYS = [
   "advisorAutoLoopGate",
   "advisorSessionSummary",
   "advisorScoutEnabled",
+  "showUsageDetails",
+  "showUsageFooter",
   "simpleMode",
   "alwaysOn",
   "advisorHerdrIntegration",
@@ -478,6 +498,8 @@ const resetDefaults = () => {
   advisorUntrackedContentRef = false;
   advisorTrackedFileContentRef = false;
   advisorScoutEnabledRef = false;
+  showUsageDetailsRef = true;
+  showUsageFooterRef = false;
 };
 
 const applyOptionalConfig = <Key extends keyof AdvisorConfig>(
@@ -545,6 +567,8 @@ const applyConfig = (config: AdvisorConfig) => {
     setAdvisorSessionSummaryRef
   );
   applyOptionalConfig(config, "advisorScoutEnabled", setAdvisorScoutEnabledRef);
+  applyOptionalConfig(config, "showUsageDetails", setShowUsageDetailsRef);
+  applyOptionalConfig(config, "showUsageFooter", setShowUsageFooterRef);
   applyOptionalConfig(config, "simpleMode", setSimpleModeRef);
   applyOptionalConfig(config, "alwaysOn", setAlwaysOnRef);
   applyOptionalConfig(config, "gateFailureMode", setAdvisorFailureModeRef);
@@ -712,6 +736,8 @@ export const saveConfig = (_ctx: ExtensionContext) => {
     advisorUntrackedContent: advisorUntrackedContentRef,
     alwaysOn: alwaysOnRef,
     gateFailureMode: advisorFailureModeRef,
+    showUsageDetails: showUsageDetailsRef,
+    showUsageFooter: showUsageFooterRef,
     simpleMode: simpleModeRef,
   };
   writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`);

package/src/model-stream.ts

@@ -56,6 +56,129 @@ export interface CollectedTextStream {
   usage?: unknown;
 }
 
+export const ADVISOR_STREAM_UPDATE_INTERVAL_MS = 90;
+
+export interface CoalescedUpdateResult {
+  error?: unknown;
+  failed: boolean;
+}
+
+export interface CoalescedUpdate<T> {
+  cancel: () => void;
+  flush: () => CoalescedUpdateResult;
+  update: (value: T) => void;
+}
+
+export interface CoalescedUpdateScheduler {
+  clearTimeout: (timer: ReturnType<typeof setTimeout>) => void;
+  now: () => number;
+  setTimeout: (
+    callback: () => void,
+    delay: number
+  ) => ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Keep stream updates responsive without forwarding every provider delta to
+ * the UI. The first update in a burst is immediate; later updates are kept as
+ * the latest value and published at most once per interval. `flush()` closes
+ * the publisher and is intended for terminal success/error paths.
+ */
+export const createCoalescedUpdate = <T>(
+  publish: (value: T) => void,
+  intervalMs = ADVISOR_STREAM_UPDATE_INTERVAL_MS,
+  scheduler: CoalescedUpdateScheduler = {
+    clearTimeout,
+    now: Date.now,
+    setTimeout: (callback, delay) => setTimeout(callback, delay),
+  }
+): CoalescedUpdate<T> => {
+  if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
+    throw new Error("Coalesced update interval must be positive and finite.");
+  }
+
+  let closed = false;
+  let hasPending = false;
+  let pending: T | undefined;
+  let lastPublishedAt: number | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let publishError: unknown;
+  let publishFailed = false;
+
+  const clearTimer = () => {
+    if (timer !== undefined) {
+      scheduler.clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  const publishPending = () => {
+    timer = undefined;
+    if (!hasPending) {
+      return;
+    }
+    const value = pending as T;
+    pending = undefined;
+    hasPending = false;
+    lastPublishedAt = scheduler.now();
+    try {
+      publish(value);
+    } catch (error) {
+      publishFailed = true;
+      publishError = error;
+      closed = true;
+      clearTimer();
+    }
+  };
+
+  const schedule = () => {
+    const elapsed =
+      lastPublishedAt === undefined
+        ? intervalMs
+        : scheduler.now() - lastPublishedAt;
+    const delay = Math.max(0, intervalMs - elapsed);
+    if (delay === 0) {
+      publishPending();
+      return;
+    }
+    timer = scheduler.setTimeout(publishPending, delay);
+    timer.unref?.();
+  };
+
+  return {
+    cancel: () => {
+      closed = true;
+      clearTimer();
+      pending = undefined;
+      hasPending = false;
+    },
+    flush: () => {
+      if (!closed) {
+        closed = true;
+        clearTimer();
+        publishPending();
+      }
+      return { error: publishError, failed: publishFailed };
+    },
+    update: (value) => {
+      if (closed) {
+        return;
+      }
+      if (publishFailed) {
+        throw publishError;
+      }
+      pending = value;
+      hasPending = true;
+      if (timer === undefined) {
+        schedule();
+      }
+      if (publishFailed) {
+        throw publishError;
+      }
+    },
+  };
+};
+
 export const collectTextStream = async (
   resolved: ResolvedConfiguredModel,
   options: CollectTextStreamOptions,

package/src/scout-context.ts

@@ -169,9 +169,14 @@ const pendingInvocationDisclosure = (
 
 export interface BuildScoutManifestOptions {
   currentInvocationId?: string;
+  /** @deprecated Use maxManifestBytes for the Scout transport budget. */
   maxBytes?: number;
+  /** Maximum reconstructed Advisor conversation characters. */
+  maxConversationChars?: number;
   maxGroupBytes?: number;
   maxGroups?: number;
+  /** Maximum serialized group-manifest bytes sent to Scout. */
+  maxManifestBytes?: number;
   policies?: AdvisorToolPolicies;
   redact?: boolean;
   toolResultMaxBytes?: number;
@@ -191,9 +196,13 @@ export const buildScoutManifest = (
     options.toolResultMaxLines ?? advisorToolResultMaxLinesRef;
   const toolResultMaxBytes =
     options.toolResultMaxBytes ?? advisorToolResultMaxBytesRef;
-  const maxBytes = options.maxBytes ?? SCOUT_MANIFEST_MAX_BYTES;
-  const maxGroups = options.maxGroups ?? SCOUT_MANIFEST_MAX_GROUPS;
-  const maxGroupBytes = options.maxGroupBytes ?? SCOUT_GROUP_MAX_BYTES;
+  const {
+    maxBytes,
+    maxConversationChars,
+    maxGroupBytes = SCOUT_GROUP_MAX_BYTES,
+    maxGroups = SCOUT_MANIFEST_MAX_GROUPS,
+    maxManifestBytes = maxBytes ?? SCOUT_MANIFEST_MAX_BYTES,
+  } = options;
 
   let latestUserIndex = -1;
   const callOwners = new Map<string, { index: number; name: string }>();
@@ -423,7 +432,7 @@ export const buildScoutManifest = (
   const availableBytes =
     groups.reduce((sum, group) => sum + groupWireBytes(group), 0) +
     protocolOmittedBytes;
-  if (maxBytes <= 0) {
+  if (maxManifestBytes <= 0) {
     return {
       manifest: {
         availableBytes: 0,
@@ -439,22 +448,39 @@ export const buildScoutManifest = (
   if (
     required.some((group) => group.bytes > maxGroupBytes) ||
     required.length > maxGroups ||
-    required.reduce((sum, group) => sum + groupWireBytes(group), 0) > maxBytes
+    required.reduce((sum, group) => sum + groupWireBytes(group), 0) >
+      maxManifestBytes
   ) {
     return {
       message:
-        "Required Scout context exceeds a fixed manifest or per-group limit.",
+        "Required Scout context exceeds the Scout manifest transport limit.",
+      ok: false,
+      reason: "required-group-overflow",
+    };
+  }
+  const contentChars = (items: ScoutContextGroup[]) =>
+    items.reduce((sum, group) => sum + group.content.length, 0) +
+    Math.max(0, items.length - 1) * 2;
+  if (
+    maxConversationChars !== undefined &&
+    contentChars(required) > maxConversationChars
+  ) {
+    return {
+      message:
+        "Required Scout context exceeds the Advisor conversation budget.",
       ok: false,
       reason: "required-group-overflow",
     };
   }
-
   const selected = groups.filter(
     (group) => group.required || group.bytes <= maxGroupBytes
   );
   const fits = () =>
     selected.length <= maxGroups &&
-    selected.reduce((sum, group) => sum + groupWireBytes(group), 0) <= maxBytes;
+    selected.reduce((sum, group) => sum + groupWireBytes(group), 0) <=
+      maxManifestBytes &&
+    (maxConversationChars === undefined ||
+      contentChars(selected) <= maxConversationChars);
   while (!fits()) {
     const optionalIndex = selected.findIndex((group) => !group.required);
     if (optionalIndex < 0) {

package/src/scout.ts

@@ -13,7 +13,7 @@ import {
   SCOUT_SYNTHESIS_MAX_BYTES,
   type ScoutManifest,
 } from "./scout-context.js";
-import type { BenchmarkTelemetry } from "./telemetry.js";
+import { snapshotAdvisorUsage } from "./usage.js";
 
 export const SCOUT_TIMEOUT_MS = 30_000;
 
@@ -224,42 +224,12 @@ export const runAdvisorScout = async (
   parentSignal?: AbortSignal,
   onEvent?: (event: ScoutLifecycleEvent) => void,
   timeoutMs = SCOUT_TIMEOUT_MS,
-  dependencies: ScoutDependencies = defaultDependencies,
-  telemetry?: BenchmarkTelemetry
+  dependencies: ScoutDependencies = defaultDependencies
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: cancellation, timeout, provider, and schema outcomes remain explicitly distinct.
 ): Promise<ScoutOutcome> => {
   const startedAt = Date.now();
   const publish = (event: ScoutLifecycleEvent) => {
     onEvent?.(event);
-    if (event.type === "chunk") {
-      return;
-    }
-    if (event.type === "call" || event.type === "cancelled") {
-      telemetry?.scout(event);
-    } else if (event.type === "success") {
-      telemetry?.scout({
-        availableCount: event.outcome.metrics.availableCount,
-        latencyMs: event.outcome.metrics.latencyMs,
-        model: event.outcome.model,
-        omittedBeforeScout: event.outcome.metrics.omittedBeforeScout,
-        selectedCount: event.outcome.metrics.selectedCount,
-        selectedLabels: event.outcome.selectedLabels,
-        synthesis: event.outcome.selection.synthesis,
-        type: "success",
-        usage: event.outcome.metrics.usage,
-      });
-    } else {
-      telemetry?.scout({
-        availableCount: event.outcome.metrics.availableCount,
-        fallback: `${event.outcome.category}: ${event.outcome.message}`,
-        latencyMs: event.outcome.metrics.latencyMs,
-        model: event.outcome.model,
-        omittedBeforeScout: event.outcome.metrics.omittedBeforeScout,
-        selectedCount: event.outcome.metrics.selectedCount,
-        type: "fallback",
-        usage: event.outcome.metrics.usage,
-      });
-    }
   };
   if (parentSignal?.aborted) {
     publish({ type: "cancelled" });
@@ -361,7 +331,10 @@ export const runAdvisorScout = async (
         ? ("invalid-selection" as const)
         : ("empty-response" as const),
       message,
-      metrics: { ...baseMetrics(manifest, startedAt), usage: streamed.usage },
+      metrics: {
+        ...baseMetrics(manifest, startedAt),
+        usage: snapshotAdvisorUsage(streamed.usage),
+      },
       model: executorRef,
       ok: false as const,
     };
@@ -383,7 +356,7 @@ export const runAdvisorScout = async (
           .filter((group) => group.required)
           .map((group) => group.id),
       ]).size,
-      usage: streamed.usage,
+      usage: snapshotAdvisorUsage(streamed.usage),
     },
     model: executorRef,
     ok: true as const,

package/src/session-state.ts

@@ -1,3 +1,11 @@
+import {
+  type AdvisorUsageTotals,
+  addAdvisorUsage,
+  emptyAdvisorUsageTotals,
+  formatAdvisorUsageStatus,
+  formatAdvisorUsageTotals,
+} from "./usage.js";
+
 export type GateDecision = "proceed" | "revise" | "blocked";
 export type ConsultationTrigger = "manual" | "executor-requested";
 export type GateTrigger =
@@ -116,10 +124,12 @@ export class AdvisorSessionState {
     string,
     { advice: string; trigger: ConsultationTrigger }
   >();
+  readonly #pendingAdvice = new Set<string>();
   readonly #reportedAdvice = new Set<string>();
   #draftConsultations = 0;
   #outcomes = 0;
   #lastAdvice?: string;
+  #usage = emptyAdvisorUsageTotals();
 
   resetTask() {
     this.#previousSignature = undefined;
@@ -129,10 +139,12 @@ export class AdvisorSessionState {
     this.#loopInterventions = 0;
     this.#consumedCalls = 0;
     this.#issuedAdvice.clear();
+    this.#pendingAdvice.clear();
     this.#reportedAdvice.clear();
     this.#draftConsultations = 0;
     this.#outcomes = 0;
     this.#lastAdvice = undefined;
+    this.#usage = emptyAdvisorUsageTotals();
   }
 
   clearBlocked() {
@@ -182,8 +194,19 @@ export class AdvisorSessionState {
     return this.#consumedCalls;
   }
 
+  /** Returns a copy of cumulative direct Advisor usage for this session. */
+  get usageTotals(): AdvisorUsageTotals {
+    return { ...this.#usage };
+  }
+
+  /** Returns the footer-ready direct Advisor usage status for this session. */
+  usageStatus() {
+    return formatAdvisorUsageStatus(this.#usage);
+  }
+
   recordInvocation(record: AdvisorInvocationRecord) {
     this.#invocations.push(record);
+    addAdvisorUsage(this.#usage, record.usage);
   }
   issueAdvice(
     id: string,
@@ -216,16 +239,38 @@ export class AdvisorSessionState {
     return true;
   }
 
-  claimAdvice(id: string) {
-    if (this.#reportedAdvice.has(id)) {
+  reserveAdvice(id: string) {
+    if (this.#reportedAdvice.has(id) || this.#pendingAdvice.has(id)) {
       return;
     }
     const advice = this.#issuedAdvice.get(id);
     if (!advice) {
       return;
     }
+    this.#pendingAdvice.add(id);
+    return advice;
+  }
+
+  commitAdvice(id: string) {
+    if (!this.#pendingAdvice.delete(id)) {
+      return false;
+    }
     this.#reportedAdvice.add(id);
     this.#outcomes += 1;
+    return true;
+  }
+
+  releaseAdvice(id: string) {
+    this.#pendingAdvice.delete(id);
+  }
+
+  /** Compatibility helper for synchronous callers that can commit immediately. */
+  claimAdvice(id: string) {
+    const advice = this.reserveAdvice(id);
+    if (!advice) {
+      return;
+    }
+    this.commitAdvice(id);
     return advice;
   }
 
@@ -271,6 +316,7 @@ export class AdvisorSessionState {
       `Triggers: ${["manual", "executor-requested", "repeated-tool-call", "completion-review", "custom-rule"].filter((trigger) => countTrigger(trigger as AdvisorTrigger) > 0).join(", ") || "none"}`,
       `Models: ${models}`,
       `Budget: ${budget}`,
+      `Usage: ${formatAdvisorUsageTotals(this.#usage)}`,
       `Markdown advice: ${markdown.length} responses (${this.#draftConsultations} with drafts)`,
       `Outcome reports: ${this.#outcomes}`,
       `Gate decisions: ${decisions}`,