pi-advisor-flow 0.5.5 → 0.6.0

package/src/scout-reconstruct.ts

@@ -0,0 +1,44 @@
+import type { ScoutManifest } from "./scout-types.ts";
+
+const prefixWithinCharBudget = (value: string, maxChars: number) => {
+  let result = "";
+  for (const character of value) {
+    if (result.length + character.length > maxChars) {
+      break;
+    }
+    result += character;
+  }
+  return result;
+};
+
+export const reconstructScoutConversation = (
+  manifest: ScoutManifest,
+  selectedIds: string[],
+  synthesis?: string,
+  maxChars = Number.MAX_SAFE_INTEGER
+): string => {
+  const selected = new Set(selectedIds);
+  const evidence = manifest.groups
+    .filter((group) => group.required || selected.has(group.id))
+    .sort((left, right) => left.originalIndex - right.originalIndex)
+    .map((group) => group.content);
+  const evidenceText = evidence.join("\n\n");
+  if (maxChars <= 0) {
+    return "";
+  }
+  if (evidenceText.length >= maxChars) {
+    return prefixWithinCharBudget(evidenceText, maxChars);
+  }
+  const inference = synthesis?.trim()
+    ? `[Scout synthesis — untrusted, non-authoritative inference; not evidence]\n${synthesis.trim()}`
+    : undefined;
+  if (!inference) {
+    return evidenceText;
+  }
+  const separator = evidenceText ? "\n\n" : "";
+  const remaining = maxChars - evidenceText.length - separator.length;
+  if (remaining <= 0) {
+    return evidenceText;
+  }
+  return `${evidenceText}${separator}${prefixWithinCharBudget(inference, remaining)}`;
+};

package/src/scout-types.ts

@@ -0,0 +1,66 @@
+/** Shared Scout manifest types and transport limits. */
+
+import type { AdvisorToolPolicies } from "./config/types.ts";
+
+export const SCOUT_MANIFEST_MAX_BYTES = 64 * 1024;
+export const SCOUT_MANIFEST_MAX_GROUPS = 64;
+export const SCOUT_GROUP_MAX_BYTES = 24 * 1024;
+export const SCOUT_LABEL_MAX_CHARS = 160;
+export const SCOUT_SELECTION_MAX_IDS = 32;
+export const SCOUT_SYNTHESIS_MAX_BYTES = 4 * 1024;
+
+export type ScoutGroupKind =
+  | "compaction"
+  | "user"
+  | "assistant"
+  | "tool-exchange"
+  | "pending-invocation";
+
+export interface ScoutContextGroup {
+  bytes: number;
+  content: string;
+  id: string;
+  kind: ScoutGroupKind;
+  label: string;
+  originalIndex: number;
+  required: boolean;
+}
+
+export interface ScoutManifest {
+  availableBytes: number;
+  availableCount: number;
+  groups: ScoutContextGroup[];
+  omittedBytes: number;
+  omittedCount: number;
+}
+
+export type ScoutManifestResult =
+  | { ok: true; manifest: ScoutManifest }
+  | {
+      ok: false;
+      reason: "invalid-protocol" | "required-group-overflow";
+      message: string;
+    };
+
+/** The invalid-protocol failure shape produced by protocol passes. */
+export interface InvalidProtocolResult {
+  message: string;
+  ok: false;
+  reason: "invalid-protocol";
+}
+
+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;
+  toolResultMaxLines?: number;
+}

package/src/scout.ts

@@ -1,21 +1,22 @@
 import type { Message } from "@earendil-works/pi-ai/compat";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { executorEffortRef, executorRef } from "./config/state.js";
+import { executorEffortRef, executorRef } from "./config/state.ts";
 import {
   type CollectedTextStream,
   collectTextStream,
   type ResolvedConfiguredModel,
   resolveConfiguredModel,
-} from "./model-stream.js";
+} from "./model-stream.ts";
+import { groupWire } from "./scout-groups.ts";
+import { reconstructScoutConversation } from "./scout-reconstruct.ts";
 import {
-  reconstructScoutConversation,
   SCOUT_SELECTION_MAX_IDS,
   SCOUT_SYNTHESIS_MAX_BYTES,
   type ScoutManifest,
-} from "./scout-context.js";
-import { snapshotAdvisorUsage } from "./usage.js";
+} from "./scout-types.ts";
+import { snapshotAdvisorUsage } from "./usage.ts";
 
-export const SCOUT_TIMEOUT_MS = 30_000;
+const SCOUT_TIMEOUT_MS = 30_000;
 
 export const SCOUT_SYSTEM = [
   "You are Scout, a context curator serving a separate engineering Advisor.",
@@ -30,7 +31,7 @@ export const SCOUT_SYSTEM = [
   "Do not use Markdown fences or add any other keys or prose.",
 ].join(" ");
 
-export type ScoutFallbackCategory =
+type ScoutFallbackCategory =
   | "required-group-overflow"
   | "invalid-protocol"
   | "missing-model"
@@ -41,7 +42,7 @@ export type ScoutFallbackCategory =
   | "invalid-selection"
   | "timeout";
 
-export interface ScoutMetrics {
+interface ScoutMetrics {
   availableCount: number;
   inputBytes: number;
   latencyMs: number;
@@ -106,14 +107,7 @@ const manifestMessage = (manifest: ScoutManifest): Message => ({
   content: [
     {
       text: JSON.stringify({
-        groups: manifest.groups.map((group) => ({
-          bytes: group.bytes,
-          content: group.content,
-          id: group.id,
-          kind: group.kind,
-          label: group.label,
-          required: group.required,
-        })),
+        groups: manifest.groups.map(groupWire),
         omittedBeforeScout: {
           bytes: manifest.omittedBytes,
           groups: manifest.omittedCount,
@@ -225,15 +219,36 @@ export const runAdvisorScout = async (
   onEvent?: (event: ScoutLifecycleEvent) => void,
   timeoutMs = SCOUT_TIMEOUT_MS,
   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 (parentSignal?.aborted) {
+  const cancelled = (): ScoutOutcome => {
     publish({ type: "cancelled" });
     return { cancelled: true, ok: false };
+  };
+  const fallback = (
+    category: ScoutFallbackCategory,
+    message: string,
+    usage?: unknown
+  ): ScoutOutcome => {
+    const outcome = {
+      category,
+      message,
+      metrics:
+        usage === undefined
+          ? baseMetrics(manifest, startedAt)
+          : { ...baseMetrics(manifest, startedAt), usage },
+      model: executorRef,
+      ok: false as const,
+    };
+    publish({ outcome, type: "fallback" });
+    return outcome;
+  };
+
+  if (parentSignal?.aborted) {
+    return cancelled();
   }
 
   let resolved: ResolvedConfiguredModel;
@@ -241,24 +256,14 @@ export const runAdvisorScout = async (
     resolved = await dependencies.resolve(ctx, executorRef, "Scout");
   } catch (error) {
     if (parentSignal?.aborted) {
-      publish({ type: "cancelled" });
-      return { cancelled: true, ok: false };
+      return cancelled();
     }
     const message = error instanceof Error ? error.message : String(error);
-    const outcome = {
-      category: classifyResolutionError(message),
-      message,
-      metrics: baseMetrics(manifest, startedAt),
-      model: executorRef,
-      ok: false as const,
-    };
-    publish({ outcome, type: "fallback" });
-    return outcome;
+    return fallback(classifyResolutionError(message), message);
   }
 
   if (parentSignal?.aborted) {
-    publish({ type: "cancelled" });
-    return { cancelled: true, ok: false };
+    return cancelled();
   }
   publish({ model: executorRef, type: "call" });
   const controller = new AbortController();
@@ -280,6 +285,12 @@ export const runAdvisorScout = async (
       once: true,
     });
   });
+  const teardown = () => {
+    clearTimeout(timer);
+    parentSignal?.removeEventListener("abort", abortFromParent);
+    controller.signal.removeEventListener("abort", onControllerAbort);
+  };
+
   let streamed: CollectedTextStream;
   try {
     const collection = dependencies.collect(resolved, {
@@ -295,30 +306,18 @@ export const runAdvisorScout = async (
     });
     streamed = await Promise.race([collection, abortPromise]);
   } catch (error) {
-    clearTimeout(timer);
-    parentSignal?.removeEventListener("abort", abortFromParent);
-    controller.signal.removeEventListener("abort", onControllerAbort);
+    teardown();
     if (parentSignal?.aborted) {
-      publish({ type: "cancelled" });
-      return { cancelled: true, ok: false };
+      return cancelled();
     }
     const message = error instanceof Error ? error.message : String(error);
-    const outcome = {
-      category: timedOut ? ("timeout" as const) : ("provider-error" as const),
-      message: timedOut ? `Scout timed out after ${timeoutMs} ms.` : message,
-      metrics: baseMetrics(manifest, startedAt),
-      model: executorRef,
-      ok: false as const,
-    };
-    publish({ outcome, type: "fallback" });
-    return outcome;
+    return timedOut
+      ? fallback("timeout", `Scout timed out after ${timeoutMs} ms.`)
+      : fallback("provider-error", message);
   }
-  clearTimeout(timer);
-  parentSignal?.removeEventListener("abort", abortFromParent);
-  controller.signal.removeEventListener("abort", onControllerAbort);
+  teardown();
   if (parentSignal?.aborted) {
-    publish({ type: "cancelled" });
-    return { cancelled: true, ok: false };
+    return cancelled();
   }
 
   let selection: ScoutSelection;
@@ -326,20 +325,11 @@ export const runAdvisorScout = async (
     selection = parseScoutSelection(streamed.text, manifest);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    const outcome = {
-      category: streamed.text.trim()
-        ? ("invalid-selection" as const)
-        : ("empty-response" as const),
+    return fallback(
+      streamed.text.trim() ? "invalid-selection" : "empty-response",
       message,
-      metrics: {
-        ...baseMetrics(manifest, startedAt),
-        usage: snapshotAdvisorUsage(streamed.usage),
-      },
-      model: executorRef,
-      ok: false as const,
-    };
-    publish({ outcome, type: "fallback" });
-    return outcome;
+      snapshotAdvisorUsage(streamed.usage)
+    );
   }
 
   const outcome = {

package/src/session-state.ts

@@ -4,7 +4,7 @@ import {
   emptyAdvisorUsageTotals,
   formatAdvisorUsageStatus,
   formatAdvisorUsageTotals,
-} from "./usage.js";
+} from "./usage.ts";
 
 export type GateDecision = "proceed" | "revise" | "blocked";
 export type ConsultationTrigger = "manual" | "executor-requested";
@@ -12,8 +12,8 @@ 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 +113,64 @@ 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; 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();
 
   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();
   }
 
   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 +187,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;
   }
 
@@ -196,17 +216,17 @@ export class AdvisorSessionState {
 
   /** 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,
@@ -214,14 +234,15 @@ export class AdvisorSessionState {
     trigger: ConsultationTrigger,
     draft = false
   ) {
-    this.#issuedAdvice.set(id, { advice, trigger });
-    this.#lastAdvice = advice;
+    this.#ledger.issued.set(id, { advice, trigger });
+    this.#ledger.lastAdvice = advice;
     if (draft) {
-      this.#draftConsultations += 1;
+      this.#ledger.draftConsultations += 1;
     }
   }
   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 +251,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 +295,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,32 +310,60 @@ 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",
+        "repeated-tool-call",
+        "completion-review",
+        "custom-rule",
+      ]
+        .filter((trigger) => this.#countTrigger(trigger as AdvisorTrigger) > 0)
+        .join(", ") || "none"
+    );
+  }
+
+  summary(limit: number | undefined) {
+    const { invocations, totals } = this.#usage;
+    if (invocations.length === 0 && this.#repetition.interventions === 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"}`,
     ].join("\n");