pi-advisor-flow 0.5.5 → 0.6.0

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,
+  };
+};

package/src/tools/consultation.ts

@@ -3,201 +3,60 @@ import type { Message } from "@earendil-works/pi-ai/compat";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
   advisorEffortRef,
-  advisorGitContextMaxCharsRef,
-  advisorGitContextRef,
   advisorRedactSecretsRef,
   advisorRef,
-  advisorScoutEnabledRef,
-  advisorTrackedFileContentRef,
-  advisorUntrackedContentRef,
-  contextMaxCharsRef,
-  executorRef,
-} from "../config/state.js";
-import { loadConfig } from "../config/storage.js";
-import { redactAndCapText, redactSecrets } from "../conversation.js";
-import {
-  clampGitContextLevel,
-  collectGitContext,
-  type GitContextLevel,
-} from "../git.js";
-import { collectTextStream, resolveConfiguredModel } from "../model-stream.js";
-import { readProjectPreferences } from "../preferences.js";
-import {
-  runAdvisorScout,
-  type ScoutLifecycleEvent,
-  type ScoutOutcome,
-} from "../scout.js";
-import {
-  buildScoutManifest,
-  reconstructScoutConversation,
-  SCOUT_MANIFEST_MAX_BYTES,
-} from "../scout-context.js";
-import type { ConsultationTrigger, GateTrigger } from "../session-state.js";
-import { readTrackedFiles, readUntrackedFiles } from "../untracked.js";
-import { parseAutomaticDecision } from "./gate-protocol.js";
+} from "../config/state.ts";
+import { loadConfig } from "../config/storage.ts";
+import type { GitContextLevel } from "../git.ts";
+import { collectTextStream, resolveConfiguredModel } from "../model-stream.ts";
+import { redactSecrets } from "../redaction.ts";
+import type { ScoutLifecycleEvent } from "../scout.ts";
+import type { ConsultationTrigger, GateTrigger } from "../session-state.ts";
+import { assembleConsultationContext } from "./consult-context.ts";
+import { parseAutomaticDecision } from "./gate-protocol.ts";
 import {
   ADVISOR_DECISION_SYSTEM,
   ADVISOR_SYSTEM,
-  advisorGitContextBudget,
   advisorMessageText,
-  advisorRepositoryContext,
-  advisorRequestConversation,
-} from "./prompts.js";
-import type { AdvisorConsultationResult, AdvisorGateOutcome } from "./types.js";
+} from "./prompts.ts";
+import type { AdvisorConsultationResult, AdvisorGateOutcome } from "./types.ts";
 
-export const curateAdvisorConversation = async (
-  ctx: ExtensionContext,
-  legacyConversation: string,
-  signal?: AbortSignal,
-  onScout?: (event: ScoutLifecycleEvent) => void,
-  enabled = advisorScoutEnabledRef,
-  runScout: typeof runAdvisorScout = runAdvisorScout,
-  currentInvocationId?: string,
-  maxChars?: number
-): Promise<{
-  conversation: string;
-  scout?: Exclude<ScoutOutcome, { cancelled: true }>;
-}> => {
-  if (!enabled) {
-    return { conversation: legacyConversation };
-  }
-  if (maxChars !== undefined && maxChars <= 0) {
-    return { conversation: "" };
-  }
-  const built = buildScoutManifest(ctx, {
-    currentInvocationId,
-    maxConversationChars: maxChars,
-    maxManifestBytes: SCOUT_MANIFEST_MAX_BYTES,
-  });
-  if (!built.ok) {
-    const scout: Exclude<ScoutOutcome, { cancelled: true }> = {
-      category: built.reason,
-      message: built.message,
-      metrics: {
-        availableCount: 0,
-        inputBytes: 0,
-        latencyMs: 0,
-        omittedBeforeScout: 0,
-        selectedCount: 0,
-      },
-      model: executorRef,
-      ok: false,
-    };
-    onScout?.({ outcome: scout, type: "fallback" });
-    return { conversation: legacyConversation, scout };
-  }
-  const outcome = await runScout(
-    ctx,
-    built.manifest,
-    signal,
-    onScout,
-    undefined,
-    undefined
-  );
-  if (!outcome.ok && outcome.cancelled) {
-    throw signal?.reason instanceof Error
-      ? signal.reason
-      : new Error("Advisor operation cancelled during Scout.");
-  }
-  let conversation = legacyConversation;
-  if (outcome.ok) {
-    conversation =
-      maxChars === undefined
-        ? outcome.conversation
-        : reconstructScoutConversation(
-            built.manifest,
-            outcome.selection.selectedIds,
-            outcome.selection.synthesis,
-            maxChars
-          );
+// biome-ignore lint/performance/noBarrelFile: preserves the tools facade's historical re-export of the moved curation entry point.
+export { curateAdvisorConversation } from "../scout-curation.ts";
+
+/** Thrown when the Advisor produced an empty response body. */
+class AdvisorNoAdviceError extends Error {
+  constructor() {
+    super("Advisor returned no advice.");
+    this.name = "AdvisorNoAdviceError";
   }
-  return { conversation, scout: outcome };
-};
+}
+
+interface CollectAdvisorResponseOptions {
+  ctx: ExtensionContext;
+  currentInvocationId?: string;
+  draft?: string;
+  gitContext?: GitContextLevel;
+  includeTracked?: string[];
+  includeUntracked?: string[];
+  onChunk?: (thinking: string, text: string) => void;
+  onScout?: (event: ScoutLifecycleEvent) => void;
+  question?: string;
+  signal?: AbortSignal;
+  systemPrompt: string;
+}
+
+const fileTag = (item: { path: string; text: string }) =>
+  `<file path=${JSON.stringify(item.path)}>\n${item.text}\n</file>`;
 
 const collectAdvisorResponse = async (
-  ctx: ExtensionContext,
-  systemPrompt: string,
-  question: string | undefined,
-  signal: AbortSignal | undefined,
-  onChunk: ((thinking: string, text: string) => void) | undefined,
-  gitContext?: GitContextLevel,
-  draft?: string,
-  includeUntracked?: string[],
-  includeTracked?: string[],
-  onScout?: (event: ScoutLifecycleEvent) => void,
-  currentInvocationId?: string
+  options: CollectAdvisorResponseOptions
 ) => {
+  const { ctx, question, signal, systemPrompt } = options;
   loadConfig(ctx);
   const resolved = await resolveConfiguredModel(ctx, advisorRef, "Advisor");
+  const context = await assembleConsultationContext(options);
 
-  // The user setting is the ceiling; the Executor may only narrow it.
-  const allowed = advisorGitContextRef;
-  const level = clampGitContextLevel(gitContext ?? allowed, allowed);
-  const gitBudget = advisorGitContextBudget(
-    contextMaxCharsRef,
-    advisorGitContextMaxCharsRef
-  );
-  const changes = collectGitContext(
-    ctx.cwd,
-    level,
-    gitBudget,
-    advisorRedactSecretsRef ? redactSecrets : undefined
-  );
-  // The note is placed first so a cap can never drop the statement that the
-  // Advisor's view of the repository is limited.
-  // 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,
-    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,
-    signal,
-    onScout,
-    advisorScoutEnabledRef,
-    runAdvisorScout,
-    currentInvocationId,
-    conversationBudget
-  );
-  const { conversation, scout } = curated;
-  const preferences = await readProjectPreferences(
-    ctx,
-    8 * 1024,
-    advisorRedactSecretsRef
-  );
-  const draftText = draft
-    ? redactAndCapText(draft, 8 * 1024, advisorRedactSecretsRef)
-    : undefined;
-  const untracked = await readUntrackedFiles(
-    ctx.cwd,
-    includeUntracked ?? [],
-    advisorUntrackedContentRef,
-    advisorRedactSecretsRef
-  );
-  const tracked = await readTrackedFiles(
-    ctx.cwd,
-    includeTracked ?? [],
-    advisorTrackedFileContentRef,
-    advisorRedactSecretsRef,
-    Math.max(
-      0,
-      24 * 1024 - untracked.reduce((sum, item) => sum + item.bytes, 0)
-    )
-  );
   // Keep the original question available to local UI callers, but never send
   // its credential-shaped values to the provider when redaction is enabled.
   const outboundQuestion =
@@ -209,19 +68,13 @@ const collectAdvisorResponse = async (
       content: [
         {
           text: advisorMessageText(
-            conversation,
+            context.conversation,
             outboundQuestion,
-            changeText,
-            draftText,
-            preferences?.text,
-            untracked.map(
-              (item) =>
-                `<file path=${JSON.stringify(item.path)}>\n${item.text}\n</file>`
-            ),
-            tracked.map(
-              (item) =>
-                `<file path=${JSON.stringify(item.path)}>\n${item.text}\n</file>`
-            )
+            context.changeText,
+            context.draftText,
+            context.preferences?.text,
+            context.untracked.map(fileTag),
+            context.tracked.map(fileTag)
           ),
           type: "text",
         },
@@ -233,27 +86,29 @@ const collectAdvisorResponse = async (
 
   const streamed = await collectTextStream(resolved, {
     messages,
-    onChunk,
+    onChunk: options.onChunk,
     reasoning: advisorEffortRef,
     signal,
     systemPrompt,
   });
   const markdown = streamed.text;
   if (!markdown.trim()) {
-    throw new Error("Advisor returned no advice.");
+    throw new AdvisorNoAdviceError();
   }
   return {
-    draftBytes: draftText ? Buffer.byteLength(draftText, "utf8") : undefined,
+    draftBytes: context.draftText
+      ? Buffer.byteLength(context.draftText, "utf8")
+      : undefined,
     markdown,
     model: advisorRef,
-    preferenceBytes: preferences?.bytes,
+    preferenceBytes: context.preferences?.bytes,
     thinkingText: streamed.thinking,
     trackedBytes:
-      tracked.reduce((sum, item) => sum + item.bytes, 0) || undefined,
+      context.tracked.reduce((sum, item) => sum + item.bytes, 0) || undefined,
     untrackedBytes:
-      untracked.reduce((sum, item) => sum + item.bytes, 0) || undefined,
+      context.untracked.reduce((sum, item) => sum + item.bytes, 0) || undefined,
     usage: streamed.usage,
-    ...(scout ? { scout } : {}),
+    ...(context.scout ? { scout: context.scout } : {}),
   };
 };
 
@@ -270,19 +125,19 @@ export const consultAdvisor = async (
   onScout?: (event: ScoutLifecycleEvent) => void,
   currentInvocationId?: string
 ): Promise<AdvisorConsultationResult> => {
-  const result = await collectAdvisorResponse(
+  const result = await collectAdvisorResponse({
     ctx,
-    ADVISOR_SYSTEM,
-    question,
-    signal,
-    onChunk,
-    gitContext,
+    currentInvocationId,
     draft,
-    includeUntracked,
+    gitContext,
     includeTracked,
+    includeUntracked,
+    onChunk,
     onScout,
-    currentInvocationId
-  );
+    question,
+    signal,
+    systemPrompt: ADVISOR_SYSTEM,
+  });
   return { ...result, adviceId: randomUUID(), trigger };
 };
 
@@ -296,19 +151,15 @@ export const runAdvisorGate = async (
   currentInvocationId?: string
 ): Promise<AdvisorGateOutcome> => {
   try {
-    const result = await collectAdvisorResponse(
+    const result = await collectAdvisorResponse({
       ctx,
-      ADVISOR_DECISION_SYSTEM,
-      question,
-      signal,
+      currentInvocationId,
       onChunk,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
       onScout,
-      currentInvocationId
-    );
+      question,
+      signal,
+      systemPrompt: ADVISOR_DECISION_SYSTEM,
+    });
     const parsed = parseAutomaticDecision(result.markdown);
     if (!parsed.ok) {
       return { ...parsed, usage: result.usage };
@@ -327,7 +178,7 @@ export const runAdvisorGate = async (
     const message = error instanceof Error ? error.message : String(error);
     return {
       category:
-        message === "Advisor returned no advice."
+        error instanceof AdvisorNoAdviceError
           ? "empty-response"
           : "provider-error",
       message,

package/src/tools/gate-policy.ts

@@ -8,11 +8,11 @@ import {
   getAdvisorMaxCallsPerSession,
   getAdvisorSettings,
   isSimpleMode,
-} from "../config/state.js";
-import type { GateFailureMode } from "../config/types.js";
-import { herdrAdvisorBlock, notifyHerdrAdvisorFailure } from "../herdr.js";
-import type { AdvisorSessionState } from "../session-state.js";
-import type { AdvisorGateResult, GateFailureCategory } from "./types.js";
+} from "../config/state.ts";
+import type { GateFailureMode } from "../config/types.ts";
+import { herdrAdvisorBlock, notifyHerdrAdvisorFailure } from "../herdr.ts";
+import type { AdvisorSessionState } from "../session-state.ts";
+import type { AdvisorGateResult, GateFailureCategory } from "./types.ts";
 
 export const updateAdvisorUsageStatus = (
   ctx: ExtensionContext,

package/src/tools/gate-protocol.ts

@@ -1,5 +1,5 @@
-import type { GateDecision } from "../session-state.js";
-import type { AdvisorGateFailure, AdvisorGateResult } from "./types.js";
+import type { GateDecision } from "../session-state.ts";
+import type { AdvisorGateFailure, AdvisorGateResult } from "./types.ts";
 
 const DECISION_LINE = /^Decision\s*:\s*(proceed|revise|blocked)\s*$/i;
 const CODE_FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;