pi-advisor-flow 0.5.1 → 0.5.3

package/src/tools/register-lifecycle.ts

@@ -0,0 +1,119 @@
+import {
+  advisorSessionSummaryRef,
+  getAdvisorMaxCallsPerSession,
+  isSimpleMode,
+} from "../config/state.js";
+import { loadConfig } from "../config/storage.js";
+import { herdrAdvisorBlock } from "../herdr.js";
+import { reserveAdvisorCall } from "./gate-policy.js";
+import { handleAutomaticGate } from "./loop-gate.js";
+import { advisorInvocationGuidelines } from "./prompts.js";
+import type { ToolRegistrationContext } from "./types.js";
+
+export const registerToolLifecycle = ({
+  pi,
+  reservedCalls,
+  runGate,
+  scoutStatus,
+  session,
+}: ToolRegistrationContext): void => {
+  // A throwing tool_call handler makes pi block that tool call (fail-safe), so
+  // a malformed advisor.json must not escape this handler: gating is skipped
+  // for that call and the failure is surfaced once per distinct outage. Config
+  // errors stay an Advisor concern instead of escalating into a session-wide
+  // outage.
+  let lastConfigErrorNotified: string | undefined;
+  const loadConfigOrSkipGating = (ctx: Parameters<typeof loadConfig>[0]) => {
+    try {
+      loadConfig(ctx);
+      lastConfigErrorNotified = undefined;
+      return true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (message !== lastConfigErrorNotified) {
+        lastConfigErrorNotified = message;
+        if (ctx.hasUI) {
+          ctx.ui.notify(
+            `Advisor gating skipped; configuration is invalid. ${message} Fix advisor.json.`,
+            "error"
+          );
+        }
+      }
+      return false;
+    }
+  };
+
+  pi.on("session_start", (_event, ctx) => {
+    session.resetTask();
+    reservedCalls.clear();
+    herdrAdvisorBlock.clear();
+    if (ctx?.hasUI) {
+      ctx.ui.setStatus("advisor-usage", undefined);
+    }
+  });
+
+  pi.on("before_agent_start", (_event, ctx) => {
+    if (!pi.getActiveTools().includes("ask_advisor")) {
+      return;
+    }
+    loadConfig(ctx);
+    const guidelines = advisorInvocationGuidelines();
+    const budget = isSimpleMode()
+      ? undefined
+      : session.remainingCalls(getAdvisorMaxCallsPerSession());
+    if (budget !== undefined) {
+      guidelines.push(
+        `Advisor calls remaining this session: ${budget}.\nReserve calls for material decisions, repeated failures, or final review.`
+      );
+    }
+    return guidelines.length > 0
+      ? {
+          systemPrompt: `${ctx.getSystemPrompt()}\n\nAdvisor invocation settings:\n${guidelines.map((rule) => `- ${rule}`).join("\n")}`,
+        }
+      : undefined;
+  });
+
+  pi.on("tool_call", (event, ctx) => {
+    if (session.blocked) {
+      return {
+        block: true,
+        reason: session.blockedReason ?? "Advisor session is blocked.",
+      };
+    }
+    if (!pi.getActiveTools().includes("ask_advisor")) {
+      return;
+    }
+    if (!loadConfigOrSkipGating(ctx)) {
+      // The ask_advisor execute path surfaces its own configuration errors as
+      // tool errors; every other tool must proceed without Advisor gating.
+      return;
+    }
+    const reservation = reserveAdvisorCall(event, ctx, session, reservedCalls);
+    if (event.toolName === "ask_advisor") {
+      return reservation;
+    }
+    return handleAutomaticGate(pi, event, ctx, session, runGate, scoutStatus);
+  });
+
+  pi.on("agent_settled", (_event, ctx) => {
+    // Any reservation still present never reached execute (for example because
+    // another handler blocked it or the turn was aborted).
+    reservedCalls.clear();
+    if (isSimpleMode() || session.blocked || !advisorSessionSummaryRef) {
+      return;
+    }
+    const summary = session.summary(getAdvisorMaxCallsPerSession());
+    if (summary && ctx.hasUI) {
+      ctx.ui.notify(summary, "info");
+    }
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    reservedCalls.clear();
+    scoutStatus.clear(ctx);
+    herdrAdvisorBlock.clear();
+    if (ctx?.hasUI) {
+      ctx.ui.setStatus("advisor-usage", undefined);
+    }
+  });
+};

package/src/tools/register-outcome.ts

@@ -0,0 +1,75 @@
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { advisorOutcomeLoggingRef } from "../config/state.js";
+import { loadConfig } from "../config/storage.js";
+import { textFrom } from "../conversation.js";
+import { ADOPTIONS, VALIDATIONS } from "../outcomes.js";
+import type { ToolRegistrationContext } from "./types.js";
+
+export const registerOutcomeTool = ({
+  appendOutcome: appendAdvisorOutcome,
+  pi,
+  session,
+}: ToolRegistrationContext): void => {
+  pi.registerTool({
+    description:
+      "Voluntarily record the settled adoption and validation outcome for a displayed adviceId when global outcome logging is enabled.",
+    async execute(_id, params, _signal, _update, ctx) {
+      loadConfig(ctx);
+      if (!advisorOutcomeLoggingRef) {
+        return {
+          content: [
+            { text: "Outcome logging is disabled globally.", type: "text" },
+          ],
+          details: { recorded: false },
+        };
+      }
+      const advice = session.reserveAdvice(params.adviceId);
+      if (!advice) {
+        throw new Error("Unknown, already recorded, or pending adviceId.");
+      }
+      try {
+        await appendAdvisorOutcome({
+          adoption: params.adoption as (typeof ADOPTIONS)[number],
+          advice: advice.advice,
+          trigger: advice.trigger,
+          validationStatus:
+            params.validationStatus as (typeof VALIDATIONS)[number],
+        });
+        session.commitAdvice(params.adviceId);
+        return {
+          content: [
+            { text: "Advisor outcome recorded locally.", type: "text" },
+          ],
+          details: { recorded: true },
+        };
+      } catch {
+        session.releaseAdvice(params.adviceId);
+        if (ctx.hasUI) {
+          ctx.ui.notify(
+            "Advisor outcome could not be recorded locally.",
+            "warning"
+          );
+        }
+        return {
+          content: [
+            {
+              text: "Advisor outcome was not recorded; Advisor execution remains usable.",
+              type: "text",
+            },
+          ],
+          details: { recorded: false },
+        };
+      }
+    },
+    label: "Record Advisor Outcome",
+    name: "record_advisor_outcome",
+    parameters: Type.Object({
+      adoption: Type.String({ enum: ADOPTIONS }),
+      adviceId: Type.String(),
+      validationStatus: Type.String({ enum: VALIDATIONS }),
+    }),
+    renderCall: () => new Text("[advisor] Record outcome", 0, 0),
+    renderResult: (result) => new Text(textFrom(result.content), 0, 0),
+  });
+};

package/src/tools/register-renderers.ts

@@ -0,0 +1,88 @@
+import {
+  type ExtensionAPI,
+  getMarkdownTheme,
+} from "@earendil-works/pi-coding-agent";
+import { Box, Markdown, Text } from "@earendil-works/pi-tui";
+import { getAdvisorSettings } from "../config/state.js";
+import { formatAdvisorUsage } from "../usage.js";
+import { adviceForDisplay, renderAdvisorCallBox } from "./render-common.js";
+import { renderScoutDetails } from "./scout-status.js";
+import type { GateDecision, ScoutToolDetails } from "./types.js";
+
+export const registerToolRenderers = (pi: ExtensionAPI): void => {
+  pi.registerEntryRenderer?.(
+    "advisor-scout-result",
+    (entry, { expanded }, theme) => {
+      const scout = entry.data as ScoutToolDetails;
+      const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+      renderScoutDetails(box, scout, Boolean(expanded), theme);
+      return box;
+    }
+  );
+
+  pi.registerMessageRenderer?.(
+    "advisor-loop-call",
+    (message, _options, theme) => {
+      const details = message.details as { question?: string } | undefined;
+      return renderAdvisorCallBox(details?.question, theme);
+    }
+  );
+
+  pi.registerMessageRenderer?.(
+    "advisor-loop-result",
+    (message, { expanded }, theme) => {
+      const details = message.details as
+        | {
+            advisor?: string;
+            decision?: GateDecision;
+            text?: string;
+            usage?: unknown;
+          }
+        | undefined;
+      const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+      box.addChild(
+        new Text(
+          theme.fg(
+            "warning",
+            theme.bold(`◆ ADVISOR GATE: ${details?.decision ?? "failure"}`)
+          ),
+          0,
+          0
+        )
+      );
+      if (details?.advisor) {
+        box.addChild(new Text(theme.fg("dim", `  ${details.advisor}`), 0, 0));
+      }
+      if (getAdvisorSettings().showUsageDetails) {
+        const usage = formatAdvisorUsage(details?.usage);
+        if (usage) {
+          box.addChild(new Text(theme.fg("dim", `  Usage: ${usage}`), 0, 0));
+        }
+      }
+      if (details?.text) {
+        box.addChild(
+          new Markdown(
+            adviceForDisplay(details.text, Boolean(expanded)),
+            0,
+            0,
+            getMarkdownTheme()
+          )
+        );
+      } else {
+        box.addChild(
+          new Text(
+            theme.fg(
+              "error",
+              typeof message.content === "string"
+                ? message.content
+                : "Advisor gate failed."
+            ),
+            0,
+            0
+          )
+        );
+      }
+      return box;
+    }
+  );
+};

package/src/tools/registration.ts

@@ -0,0 +1,35 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { appendOutcome } from "../outcomes.js";
+import type { AdvisorSessionState } from "../session-state.js";
+import { consultAdvisor, runAdvisorGate } from "./consultation.js";
+import { registerAskAdvisorTool } from "./register-ask-advisor.js";
+import { registerToolLifecycle } from "./register-lifecycle.js";
+import { registerOutcomeTool } from "./register-outcome.js";
+import { registerToolRenderers } from "./register-renderers.js";
+import { ScoutStatusManager } from "./scout-status.js";
+import { advisorSessionState } from "./session.js";
+import type {
+  ToolRegistrationContext,
+  ToolRegistrationDependencies,
+} from "./types.js";
+
+export const registerAdvisorTool = (
+  pi: ExtensionAPI,
+  session: AdvisorSessionState = advisorSessionState,
+  dependencies: ToolRegistrationDependencies = {}
+): void => {
+  const registration: ToolRegistrationContext = {
+    appendOutcome: dependencies.appendOutcome ?? appendOutcome,
+    consult: dependencies.consult ?? consultAdvisor,
+    pi,
+    reservedCalls: new Set<string>(),
+    runGate: dependencies.runGate ?? runAdvisorGate,
+    scoutStatus: dependencies.statusManager ?? new ScoutStatusManager(),
+    session,
+  };
+
+  registerToolRenderers(pi);
+  registerToolLifecycle(registration);
+  registerAskAdvisorTool(registration);
+  registerOutcomeTool(registration);
+};

package/src/tools/render-advisor-result.ts

@@ -0,0 +1,168 @@
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import {
+  getMarkdownTheme,
+  type Theme,
+  type ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
+import { Box, Markdown, Text } from "@earendil-works/pi-tui";
+import { getAdvisorSettings } from "../config/state.js";
+import { textFrom } from "../conversation.js";
+import { formatAdvisorUsage } from "../usage.js";
+import {
+  adviceForDisplay,
+  hasSoundVerdict,
+  renderAdvisorResponseHeader,
+  renderThinkingMarkdown,
+  SPINNER_FRAMES,
+} from "./render-common.js";
+import { renderScoutDetails } from "./scout-status.js";
+import type { AdvisorToolContext, AdvisorToolDetails } from "./types.js";
+
+const advisorResultDetails = (result: AgentToolResult<AdvisorToolDetails>) =>
+  result.details;
+
+const syncRenderPhase = (context: AdvisorToolContext, phase: string) => {
+  if (context.state.phase !== phase && context.state.timerId) {
+    clearInterval(context.state.timerId);
+    context.state.timerId = undefined;
+  }
+  context.state.phase = phase;
+};
+
+const renderPartialAdvisorResult = (
+  box: Box,
+  result: AgentToolResult<AdvisorToolDetails>,
+  expanded: boolean,
+  theme: Theme,
+  context: AdvisorToolContext
+) => {
+  const details = advisorResultDetails(result);
+  if (details?.scout) {
+    context.state.scout = details.scout;
+  }
+  const scout = details?.scout ?? context.state.scout;
+  const scoutActive =
+    scout?.status === "calling" || scout?.status === "streaming";
+  syncRenderPhase(context, scoutActive ? "scout" : "advisor");
+  if (!context.state.timerId) {
+    context.state.timerId = setInterval(() => context.invalidate(), 80);
+  }
+  if (scout) {
+    renderScoutDetails(box, scout, expanded, theme);
+  }
+  if (scoutActive || scout?.status === "cancelled") {
+    return;
+  }
+  const frame =
+    SPINNER_FRAMES[Math.floor(Date.now() / 80) % SPINNER_FRAMES.length];
+  const lines = [
+    `${theme.fg("warning", theme.bold(`◆ ADVISOR ${frame}`))} ${theme.fg("dim", "· Working…")}`,
+  ];
+  box.addChild(new Text(lines.join("\n"), 0, 0));
+  if (details?.thinking?.trim()) {
+    const thought =
+      details.thinking.length > 200
+        ? details.thinking.slice(-200)
+        : details.thinking;
+    box.addChild(renderThinkingMarkdown(thought, theme));
+  }
+  if (details?.text) {
+    box.addChild(
+      new Markdown(
+        adviceForDisplay(details.text, expanded),
+        0,
+        0,
+        getMarkdownTheme()
+      )
+    );
+  }
+};
+
+const renderFinalAdvisorResult = (
+  box: Box,
+  result: AgentToolResult<AdvisorToolDetails>,
+  expanded: boolean,
+  theme: Theme,
+  context: AdvisorToolContext
+) => {
+  syncRenderPhase(context, "final");
+  if (context.state.timerId) {
+    clearInterval(context.state.timerId);
+    context.state.timerId = undefined;
+  }
+  const details = advisorResultDetails(result);
+  if (details?.scout) {
+    context.state.scout = details.scout;
+  }
+  const scout = details?.scout ?? context.state.scout;
+  if (scout) {
+    renderScoutDetails(box, scout, expanded, theme);
+  }
+  if (scout?.status === "cancelled") {
+    return;
+  }
+  const advice = details?.text || textFrom(result.content);
+  const lines = [renderAdvisorResponseHeader(hasSoundVerdict(advice), theme)];
+  if (details?.advisor) {
+    lines.push(theme.fg("dim", `  ${details.advisor}`));
+  }
+  if (getAdvisorSettings().showUsageDetails) {
+    const usage = formatAdvisorUsage(details?.usage);
+    if (usage) {
+      lines.push(theme.fg("dim", `  Usage: ${usage}`));
+    }
+  }
+  const attachments = [
+    details?.draftBytes
+      ? `Draft attached · ${details.draftBytes} B`
+      : undefined,
+    details?.preferenceBytes
+      ? `Project preferences attached · ${details.preferenceBytes} B`
+      : undefined,
+    details?.trackedBytes
+      ? `Tracked files attached · ${details.trackedBytes} B`
+      : undefined,
+    details?.untrackedBytes
+      ? `Untracked files attached · ${details.untrackedBytes} B`
+      : undefined,
+  ].filter(Boolean);
+  if (attachments.length) {
+    lines.push(theme.fg("dim", `  ${attachments.join(" · ")}`));
+  }
+  const thinking = details?.thinking?.trim()
+    ? `${details.thinking.slice(0, 300)}${details.thinking.length > 300 ? "…" : ""}`
+    : "";
+  const displayAdvice = advice || "(Advisor returned no advice.)";
+  box.addChild(new Text(lines.join("\n"), 0, 0));
+  if (thinking) {
+    box.addChild(renderThinkingMarkdown(thinking, theme));
+  }
+  box.addChild(
+    new Markdown(
+      adviceForDisplay(displayAdvice, expanded),
+      0,
+      0,
+      getMarkdownTheme()
+    )
+  );
+};
+
+export const renderAdvisorResult = (
+  result: AgentToolResult<AdvisorToolDetails>,
+  { isPartial, expanded }: ToolRenderResultOptions,
+  theme: Theme,
+  context: AdvisorToolContext
+) => {
+  const box =
+    context.lastComponent instanceof Box
+      ? context.lastComponent
+      : new Box(1, 1, (text: string) => theme.bg("customMessageBg", text));
+  box.setBgFn((text) => theme.bg("customMessageBg", text));
+  box.clear();
+  if (isPartial) {
+    renderPartialAdvisorResult(box, result, expanded, theme, context);
+  } else {
+    renderFinalAdvisorResult(box, result, expanded, theme, context);
+  }
+  return box;
+};

package/src/tools/render-common.ts

@@ -0,0 +1,120 @@
+import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
+import {
+  Box,
+  type Component,
+  Markdown,
+  Text,
+  truncateToWidth,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
+import { advisorCollapseResponsesRef } from "../config/state.js";
+
+export const SPINNER_FRAMES = [
+  "⠋",
+  "⠙",
+  "⠹",
+  "⠸",
+  "⠼",
+  "⠴",
+  "⠦",
+  "⠧",
+  "⠇",
+  "⠏",
+];
+
+const THINKING_PREFIX = "  💭 ";
+const THINKING_PREFIX_WIDTH = visibleWidth(THINKING_PREFIX);
+export type ThinkingTheme = Pick<Theme, "fg">;
+
+/**
+ * Renders visible nested-model thinking with the same Markdown semantics as
+ * Pi's assistant thinking blocks while keeping the compact speech-bubble cue.
+ * The prefix is added after Markdown parsing so it cannot change block syntax.
+ *
+ * Note: During streaming, incomplete Markdown (e.g., `**text` without closing **)
+ * displays raw markers transiently until delimiters arrive. This mirrors expected
+ * behavior when typing Markdown incrementally and is acceptable in the context
+ * of brief thinking previews. When thinking is complete, all markers render.
+ */
+class ThinkingMarkdown implements Component {
+  private readonly markdown: Markdown;
+  private readonly prefix: string;
+
+  constructor(thinking: string, theme: ThinkingTheme) {
+    this.markdown = new Markdown(thinking.trim(), 0, 0, getMarkdownTheme(), {
+      color: (text) => theme.fg("thinkingText", text),
+      italic: true,
+    });
+    this.prefix = theme.fg("thinkingText", THINKING_PREFIX);
+  }
+
+  render(width: number): string[] {
+    const renderWidth = Math.max(1, Math.floor(width));
+    const contentWidth = Math.max(1, renderWidth - THINKING_PREFIX_WIDTH);
+    const lines = this.markdown.render(contentWidth);
+    return lines.map((line, index) =>
+      truncateToWidth(
+        index === 0 ? `${this.prefix}${line}` : line,
+        renderWidth,
+        ""
+      )
+    );
+  }
+
+  invalidate(): void {
+    this.markdown.invalidate();
+  }
+}
+
+export const renderThinkingMarkdown = (
+  thinking: string,
+  theme: ThinkingTheme
+): Component => new ThinkingMarkdown(thinking, theme);
+
+export const resolveAdvisorRequest = (question?: string) =>
+  question?.trim() || undefined;
+
+export const renderAdvisorCallBox = (
+  question: string | undefined,
+  theme: Theme
+) => {
+  const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+  const label = theme.fg("customMessageLabel", theme.bold("[advisor]"));
+  const title = theme.fg("customMessageText", "Executor → Advisor");
+  box.addChild(
+    new Text(
+      question
+        ? `${label} ${title}\n${theme.fg("dim", `  ${question}`)}`
+        : `${label} ${title}`,
+      0,
+      0
+    )
+  );
+  return box;
+};
+
+const COLLAPSED_ADVICE_LINES = 12;
+// The system prompt requires this exact first line, so the match is exact too.
+const SOUND_VERDICT = /^Verdict:\s*sound$/;
+
+export const hasSoundVerdict = (advice: string) =>
+  SOUND_VERDICT.test(
+    (advice.split("\n").find((line) => line.trim()) ?? "").trim()
+  );
+
+/** The single Advisor response header shared by tool and manual renderers. */
+export const renderAdvisorResponseHeader = (sound: boolean, theme: Theme) =>
+  sound
+    ? theme.fg("accent", theme.bold("◆ ADVISOR · SOUND"))
+    : theme.fg("warning", theme.bold("◆ ADVISOR RESPONSE"));
+
+export const adviceForDisplay = (advice: string, expanded: boolean) => {
+  if (!advisorCollapseResponsesRef || expanded) {
+    return advice;
+  }
+  const lines = advice.split("\n");
+  if (lines.length <= COLLAPSED_ADVICE_LINES) {
+    return advice;
+  }
+  return `${lines.slice(0, COLLAPSED_ADVICE_LINES).join("\n")}\n\n… (${lines.length - COLLAPSED_ADVICE_LINES} more lines, Ctrl+O to expand)`;
+};