pi-advisor-flow 0.5.0 → 0.5.2

package/src/conversation.ts

@@ -1,13 +1,15 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
-  type AdvisorToolPolicies,
   advisorRedactSecretsRef,
   advisorToolPoliciesRef,
   advisorToolResultMaxBytesRef,
   advisorToolResultMaxLinesRef,
+} from "./config/state.js";
+import type { AdvisorToolPolicies } from "./config/types.js";
+import {
   DEFAULT_ADVISOR_TOOL_RESULT_MAX_BYTES,
   DEFAULT_ADVISOR_TOOL_RESULT_MAX_LINES,
-} from "./config.js";
+} from "./config/types.js";
 
 type RecordValue = Record<string, unknown>;
 

package/src/herdr.ts

@@ -1,5 +1,5 @@
 import net from "node:net";
-import { getAdvisorSettings } from "./config.js";
+import { getAdvisorSettings } from "./config/state.js";
 import { redactSecrets } from "./conversation.js";
 
 // Keep the JSON-RPC method components separate from Socket's URL-string heuristic.

package/src/model-stream.ts

@@ -6,7 +6,7 @@ import {
   stream,
 } from "@earendil-works/pi-ai/compat";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { splitRef } from "./config.js";
+import { splitRef } from "./config/state.js";
 
 export interface ResolvedConfiguredModel {
   apiKey: string;
@@ -18,9 +18,12 @@ export interface ResolvedConfiguredModel {
 
 export const resolveConfiguredModel = async (
   ctx: ExtensionContext,
-  ref: string,
+  ref: string | undefined,
   label: string
 ): Promise<ResolvedConfiguredModel> => {
+  if (!ref) {
+    throw new Error(`${label} model not configured`);
+  }
   const [provider, modelId] = splitRef(ref);
   const model = ctx.modelRegistry.find(provider, modelId);
   if (!model) {
@@ -193,7 +196,13 @@ export const collectTextStream = async (
       apiKey: resolved.apiKey,
       env: resolved.env,
       headers: resolved.headers,
+      // `stream()` uses the provider-facing name while the extension's public
+      // option keeps the Pi-facing `reasoning` name. Preserve both so the
+      // configured effort reaches providers that serialize reasoning_effort.
       reasoning: options.reasoning as never,
+      ...(options.reasoning === undefined
+        ? {}
+        : { reasoningEffort: options.reasoning as never }),
       signal: options.signal,
     }
   );
@@ -209,9 +218,23 @@ export const collectTextStream = async (
   }
 
   const response = await eventStream.result();
+  if (options.signal?.aborted) {
+    throw options.signal.reason instanceof Error
+      ? options.signal.reason
+      : new Error("Advisor operation cancelled.");
+  }
   const lastAssistant = [response].find(
     (message): message is AssistantMessage => message.role === "assistant"
   );
+  if (
+    lastAssistant?.stopReason === "error" ||
+    lastAssistant?.stopReason === "aborted"
+  ) {
+    throw new Error(
+      lastAssistant.errorMessage ??
+        `Advisor stream ended with ${lastAssistant.stopReason}.`
+    );
+  }
   const finalText =
     lastAssistant?.content
       .filter(

package/src/scout-context.ts

@@ -1,12 +1,12 @@
 import { createHash } from "node:crypto";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
-  type AdvisorToolPolicies,
   advisorRedactSecretsRef,
   advisorToolPoliciesRef,
   advisorToolResultMaxBytesRef,
   advisorToolResultMaxLinesRef,
-} from "./config.js";
+} from "./config/state.js";
+import type { AdvisorToolPolicies } from "./config/types.js";
 import { conversationEntry, textFrom } from "./conversation.js";
 
 export const SCOUT_MANIFEST_MAX_BYTES = 64 * 1024;

package/src/scout.ts

@@ -1,6 +1,6 @@
 import type { Message } from "@earendil-works/pi-ai/compat";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { executorEffortRef, executorRef } from "./config.js";
+import { executorEffortRef, executorRef } from "./config/state.js";
 import {
   type CollectedTextStream,
   collectTextStream,

package/src/tools/consultation.ts

@@ -0,0 +1,337 @@
+import { randomUUID } from "node:crypto";
+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";
+import {
+  ADVISOR_DECISION_SYSTEM,
+  ADVISOR_SYSTEM,
+  advisorGitContextBudget,
+  advisorMessageText,
+  advisorRepositoryContext,
+  advisorRequestConversation,
+} from "./prompts.js";
+import type { AdvisorConsultationResult, AdvisorGateOutcome } from "./types.js";
+
+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
+          );
+  }
+  return { conversation, scout: outcome };
+};
+
+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
+) => {
+  loadConfig(ctx);
+  const resolved = await resolveConfiguredModel(ctx, advisorRef, "Advisor");
+
+  // 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 =
+    advisorRedactSecretsRef && question !== undefined
+      ? redactSecrets(question)
+      : question;
+  const messages: Message[] = [
+    {
+      content: [
+        {
+          text: advisorMessageText(
+            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>`
+            )
+          ),
+          type: "text",
+        },
+      ],
+      role: "user",
+      timestamp: Date.now(),
+    },
+  ];
+
+  const streamed = await collectTextStream(resolved, {
+    messages,
+    onChunk,
+    reasoning: advisorEffortRef,
+    signal,
+    systemPrompt,
+  });
+  const markdown = streamed.text;
+  if (!markdown.trim()) {
+    throw new Error("Advisor returned no advice.");
+  }
+  return {
+    draftBytes: draftText ? Buffer.byteLength(draftText, "utf8") : undefined,
+    markdown,
+    model: advisorRef,
+    preferenceBytes: preferences?.bytes,
+    thinkingText: streamed.thinking,
+    trackedBytes:
+      tracked.reduce((sum, item) => sum + item.bytes, 0) || undefined,
+    untrackedBytes:
+      untracked.reduce((sum, item) => sum + item.bytes, 0) || undefined,
+    usage: streamed.usage,
+    ...(scout ? { scout } : {}),
+  };
+};
+
+export const consultAdvisor = async (
+  ctx: ExtensionContext,
+  question?: string,
+  signal?: AbortSignal,
+  onChunk?: (thinking: string, text: string) => void,
+  trigger: ConsultationTrigger = "executor-requested",
+  gitContext?: GitContextLevel,
+  draft?: string,
+  includeUntracked?: string[],
+  includeTracked?: string[],
+  onScout?: (event: ScoutLifecycleEvent) => void,
+  currentInvocationId?: string
+): Promise<AdvisorConsultationResult> => {
+  const result = await collectAdvisorResponse(
+    ctx,
+    ADVISOR_SYSTEM,
+    question,
+    signal,
+    onChunk,
+    gitContext,
+    draft,
+    includeUntracked,
+    includeTracked,
+    onScout,
+    currentInvocationId
+  );
+  return { ...result, adviceId: randomUUID(), trigger };
+};
+
+export const runAdvisorGate = async (
+  ctx: ExtensionContext,
+  question: string,
+  trigger: GateTrigger = "repeated-tool-call",
+  signal?: AbortSignal,
+  onChunk?: (thinking: string, text: string) => void,
+  onScout?: (event: ScoutLifecycleEvent) => void,
+  currentInvocationId?: string
+): Promise<AdvisorGateOutcome> => {
+  try {
+    const result = await collectAdvisorResponse(
+      ctx,
+      ADVISOR_DECISION_SYSTEM,
+      question,
+      signal,
+      onChunk,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      onScout,
+      currentInvocationId
+    );
+    const parsed = parseAutomaticDecision(result.markdown);
+    if (!parsed.ok) {
+      return { ...parsed, usage: result.usage };
+    }
+    return {
+      ...parsed,
+      model: result.model,
+      thinkingText: result.thinkingText,
+      trigger,
+      usage: result.usage,
+    };
+  } catch (error) {
+    if (signal?.aborted) {
+      throw error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      category:
+        message === "Advisor returned no advice."
+          ? "empty-response"
+          : "provider-error",
+      message,
+      ok: false,
+    };
+  }
+};

package/src/tools/gate-policy.ts

@@ -0,0 +1,132 @@
+import type {
+  ExtensionContext,
+  ToolCallEvent,
+  ToolCallEventResult,
+} from "@earendil-works/pi-coding-agent";
+import {
+  advisorBlockOnBlockedRef,
+  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";
+
+export const updateAdvisorUsageStatus = (
+  ctx: ExtensionContext,
+  session: AdvisorSessionState
+) => {
+  if (ctx.hasUI) {
+    ctx.ui.setStatus(
+      "advisor-usage",
+      getAdvisorSettings().showUsageFooter ? session.usageStatus() : undefined
+    );
+  }
+};
+
+export const notifyLocalFailure = (
+  ctx: ExtensionContext,
+  message: string,
+  sessionBlocked = false
+) => {
+  if (ctx.hasUI) {
+    ctx.ui.notify(
+      `Advisor ${sessionBlocked ? "gate failure; session blocked" : "consultation failed"}: ${message}`,
+      "error"
+    );
+  }
+};
+
+export const gateFailureEffectForMode = (mode: GateFailureMode) => {
+  if (mode === "warn-and-continue") {
+    return "continued" as const;
+  }
+  return mode === "block-tool"
+    ? ("tool-blocked" as const)
+    : ("session-blocked" as const);
+};
+
+export const gateDecisionEffect = (
+  decision: AdvisorGateResult["decision"],
+  failureMode: GateFailureMode
+) => {
+  if (decision === "proceed") {
+    return "continued" as const;
+  }
+  return decision === "blocked"
+    ? gateFailureEffectForMode(failureMode)
+    : ("tool-blocked" as const);
+};
+
+export const failureEffect = (
+  category: GateFailureCategory,
+  message: string,
+  ctx: ExtensionContext,
+  session: AdvisorSessionState,
+  failureMode: GateFailureMode
+) => {
+  const reason = `Advisor gate ${category}: ${message}`;
+  notifyLocalFailure(ctx, message, failureMode === "block-session");
+  notifyHerdrAdvisorFailure("Advisor gate failure", reason);
+  if (failureMode === "warn-and-continue") {
+    return { block: false, effect: "continued" as const, reason };
+  }
+  if (failureMode === "block-tool") {
+    return { block: true, effect: "tool-blocked" as const, reason };
+  }
+  session.block(reason);
+  herdrAdvisorBlock.set(reason);
+  if (advisorBlockOnBlockedRef) {
+    ctx.abort();
+  }
+  return { block: true, effect: "session-blocked" as const, reason };
+};
+
+export const blockedDecisionEffect = (
+  reason: string,
+  ctx: ExtensionContext,
+  session: AdvisorSessionState,
+  failureMode: GateFailureMode
+) => {
+  if (failureMode === "warn-and-continue") {
+    if (ctx.hasUI) {
+      ctx.ui.notify(
+        "Advisor gate returned blocked; continuing by configuration.",
+        "warning"
+      );
+    }
+    return { block: false, effect: "continued" as const, reason };
+  }
+  if (failureMode === "block-tool") {
+    return { block: true, effect: "tool-blocked" as const, reason };
+  }
+  session.block(reason);
+  herdrAdvisorBlock.set(reason);
+  if (advisorBlockOnBlockedRef) {
+    ctx.abort();
+  }
+  return { block: true, effect: "session-blocked" as const, reason };
+};
+
+export const reserveAdvisorCall = (
+  event: ToolCallEvent,
+  ctx: ExtensionContext,
+  session: AdvisorSessionState,
+  reservedCalls: Set<string>
+): ToolCallEventResult | undefined => {
+  if (event.toolName !== "ask_advisor" || isSimpleMode()) {
+    return;
+  }
+  if (!session.canConsult(getAdvisorMaxCallsPerSession())) {
+    const message = "Advisor call budget exhausted for this session.";
+    if (ctx.hasUI) {
+      ctx.ui.notify(message, "warning");
+    }
+    notifyHerdrAdvisorFailure("Advisor budget exhausted", message);
+    return { block: true, reason: message };
+  }
+  reservedCalls.add(event.toolCallId);
+  return {};
+};

package/src/tools/gate-protocol.ts

@@ -0,0 +1,127 @@
+import type { GateDecision } from "../session-state.js";
+import type { AdvisorGateFailure, AdvisorGateResult } from "./types.js";
+
+const DECISION_LINE = /^Decision\s*:\s*(proceed|revise|blocked)\s*$/i;
+const CODE_FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const LINE_BREAK = /\r?\n/;
+
+interface FenceState {
+  character: string;
+  length: number;
+}
+
+const advanceFence = (
+  openingFence: FenceState | undefined,
+  marker: string,
+  suffix: string
+): { closed: boolean; openingFence: FenceState | undefined } => {
+  if (!openingFence) {
+    if (marker[0] === "`" && suffix.includes("`")) {
+      return { closed: false, openingFence: undefined };
+    }
+    return {
+      closed: false,
+      openingFence: { character: marker[0], length: marker.length },
+    };
+  }
+  if (
+    suffix.trim().length > 0 ||
+    marker[0] !== openingFence.character ||
+    marker.length < openingFence.length
+  ) {
+    return { closed: false, openingFence };
+  }
+  return { closed: true, openingFence: undefined };
+};
+
+export const parseAutomaticDecision = (
+  text: string
+): AdvisorGateResult | AdvisorGateFailure => {
+  const lines = text.split(LINE_BREAK);
+  const nonEmpty = lines.findIndex((line) => line.trim().length > 0);
+  if (nonEmpty === -1) {
+    return {
+      category: "empty-response",
+      message: "Advisor returned an empty gate response.",
+      ok: false,
+    };
+  }
+  const first = lines[nonEmpty].trim();
+  const match = DECISION_LINE.exec(first);
+  if (!match) {
+    return {
+      category: first.toLowerCase().startsWith("decision:")
+        ? "malformed-decision"
+        : "missing-decision",
+      markdown: text,
+      message:
+        "Advisor gate response must begin with Decision: proceed, Decision: revise, or Decision: blocked.",
+      ok: false,
+    };
+  }
+  const decision = match[1].toLowerCase() as GateDecision;
+  let openingFence: FenceState | undefined;
+  const decisions: string[] = [];
+  let pendingFencedDecisions: string[] = [];
+  for (const line of lines.slice(nonEmpty + 1)) {
+    const trimmed = line.trim();
+    // Decisions in a balanced fenced example are illustrative. Remember the
+    // opening delimiter so mismatched, undersized, or annotated fences cannot
+    // close it and hide a contradictory verdict. If the fence never closes,
+    // retain its decisions so malformed Markdown cannot make the gate fail
+    // open.
+    const fence = CODE_FENCE.exec(line);
+    if (fence) {
+      const { closed, openingFence: nextOpeningFence } = advanceFence(
+        openingFence,
+        fence[1],
+        fence[2]
+      );
+      openingFence = nextOpeningFence;
+      if (closed) {
+        pendingFencedDecisions = [];
+      }
+      continue;
+    }
+    const subsequent = DECISION_LINE.exec(trimmed);
+    if (!subsequent) {
+      continue;
+    }
+    const repeated = subsequent[1].trim().toLowerCase();
+    if (openingFence) {
+      pendingFencedDecisions.push(repeated);
+    } else {
+      decisions.push(repeated);
+    }
+  }
+  if (openingFence) {
+    decisions.push(...pendingFencedDecisions);
+  }
+  for (const repeated of decisions) {
+    if (repeated === decision) {
+      return {
+        category: "duplicate-decision",
+        markdown: text,
+        message: "Advisor gate response contains duplicate decision lines.",
+        ok: false,
+      };
+    }
+    return {
+      category: "contradictory-decision",
+      markdown: text,
+      message: "Advisor gate response contains contradictory decision lines.",
+      ok: false,
+    };
+  }
+  return {
+    decision,
+    markdown: text,
+    model: "",
+    ok: true,
+    thinkingText: "",
+    trigger: "repeated-tool-call",
+  };
+};
+
+export const adviceForGateText = (result: AdvisorGateResult) =>
+  `**Decision: ${result.decision}**\n\n${result.markdown}`;