pi-advisor-flow 0.5.0 → 0.5.2

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)`;
+};

package/src/tools/scout-status.ts

@@ -0,0 +1,206 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+import { type Box, Text } from "@earendil-works/pi-tui";
+import { executorRef, getAdvisorSettings } from "../config/state.js";
+import type { ScoutLifecycleEvent } from "../scout.js";
+import { formatAdvisorUsage, snapshotAdvisorUsage } from "../usage.js";
+import { renderThinkingMarkdown, SPINNER_FRAMES } from "./render-common.js";
+import type { ScoutToolDetails } from "./types.js";
+
+export const scoutDetailsFromEvent = (
+  event: ScoutLifecycleEvent,
+  previous?: ScoutToolDetails
+): ScoutToolDetails => {
+  if (event.type === "call") {
+    return { model: event.model, status: "calling" };
+  }
+  if (event.type === "chunk") {
+    return {
+      ...previous,
+      model: event.model,
+      status: "streaming",
+      text: event.text,
+      thinking: event.thinking,
+    };
+  }
+  if (event.type === "cancelled") {
+    return {
+      model: previous ? previous.model : executorRef,
+      status: "cancelled",
+    };
+  }
+  const { outcome } = event;
+  return outcome.ok
+    ? {
+        availableCount: outcome.metrics.availableCount,
+        latencyMs: outcome.metrics.latencyMs,
+        model: outcome.model,
+        omittedBeforeScout: outcome.metrics.omittedBeforeScout,
+        selectedCount: outcome.metrics.selectedCount,
+        selectedLabels: outcome.selectedLabels,
+        status: "curated",
+        synthesis: outcome.selection.synthesis,
+        usage: snapshotAdvisorUsage(outcome.metrics.usage),
+      }
+    : {
+        availableCount: outcome.metrics.availableCount,
+        fallbackReason: `${outcome.category}: ${outcome.message}`,
+        latencyMs: outcome.metrics.latencyMs,
+        model: outcome.model,
+        omittedBeforeScout: outcome.metrics.omittedBeforeScout,
+        selectedCount: 0,
+        status: "fallback",
+        usage: snapshotAdvisorUsage(outcome.metrics.usage),
+      };
+};
+
+export const appendScoutLifecycleEntry = (
+  pi: ExtensionAPI,
+  event: ScoutLifecycleEvent,
+  previous?: ScoutToolDetails
+) => {
+  const scout = scoutDetailsFromEvent(event, previous);
+  if (
+    event.type === "success" ||
+    event.type === "fallback" ||
+    event.type === "cancelled"
+  ) {
+    pi.appendEntry?.("advisor-scout-result", scout);
+  }
+  return scout;
+};
+
+export class ScoutStatusManager {
+  readonly #active = new Set<symbol>();
+  readonly #known = new Set<symbol>();
+  readonly #retired = new Set<symbol>();
+  private readonly showStatus: boolean;
+
+  constructor(showStatus = true) {
+    this.showStatus = showStatus;
+  }
+
+  register(token: symbol) {
+    if (!this.#retired.has(token)) {
+      this.#known.add(token);
+    }
+  }
+
+  update(ctx: ExtensionContext, token: symbol, event: ScoutLifecycleEvent) {
+    if (this.#retired.has(token) || !ctx.hasUI) {
+      return;
+    }
+    this.#known.add(token);
+    if (event.type === "call" || event.type === "chunk") {
+      this.#active.add(token);
+      if (this.showStatus) {
+        ctx.ui.setStatus("advisor-scout", "Scout curating…");
+      }
+      return;
+    }
+    this.release(ctx, token);
+  }
+
+  release(ctx: ExtensionContext, token: symbol) {
+    this.#active.delete(token);
+    this.#known.delete(token);
+    this.#retired.add(token);
+    if (!(ctx.hasUI && this.showStatus)) {
+      return;
+    }
+    ctx.ui.setStatus(
+      "advisor-scout",
+      this.#active.size > 0 ? "Scout curating…" : undefined
+    );
+  }
+
+  clear(ctx: ExtensionContext) {
+    for (const token of this.#known) {
+      this.#retired.add(token);
+    }
+    this.#known.clear();
+    this.#active.clear();
+    if (ctx.hasUI && this.showStatus) {
+      ctx.ui.setStatus("advisor-scout", undefined);
+    }
+  }
+}
+
+const scoutTitle = (scout: ScoutToolDetails, frame: string) => {
+  if (scout.status === "calling" || scout.status === "streaming") {
+    return `◆ SCOUT ${frame} · CURATING…`;
+  }
+  if (scout.status === "curated") {
+    return "◆ SCOUT · CURATED";
+  }
+  if (scout.status === "cancelled") {
+    return "◆ SCOUT · CANCELLED";
+  }
+  return "◆ SCOUT · FALLBACK";
+};
+
+export const renderScoutDetails = (
+  box: Box,
+  scout: ScoutToolDetails,
+  expanded: boolean,
+  theme: Theme
+) => {
+  const active = scout.status === "calling" || scout.status === "streaming";
+  const frame =
+    SPINNER_FRAMES[Math.floor(Date.now() / 80) % SPINNER_FRAMES.length];
+  const title = scoutTitle(scout, frame);
+  const lines = [
+    theme.fg(
+      scout.status === "fallback" || scout.status === "cancelled"
+        ? "warning"
+        : "accent",
+      theme.bold(title)
+    ),
+    theme.fg(
+      "dim",
+      `  ${scout.model}${scout.selectedCount === undefined ? "" : ` · ${scout.selectedCount} kept / ${Math.max(0, (scout.availableCount ?? 0) - scout.selectedCount)} omitted`}${scout.latencyMs === undefined ? "" : ` · ${(scout.latencyMs / 1000).toFixed(1)}s`}`
+    ),
+  ];
+  if (getAdvisorSettings().showUsageDetails) {
+    const usage = formatAdvisorUsage(scout.usage);
+    if (usage) {
+      lines.push(theme.fg("dim", `  Usage: ${usage}`));
+    }
+  }
+  if (scout.fallbackReason) {
+    lines.push(theme.fg("warning", `  ${scout.fallbackReason}`));
+  }
+  const thinking = scout.thinking && active ? scout.thinking.slice(-200) : "";
+  box.addChild(new Text(lines.join("\n"), 0, 0));
+  if (thinking.trim()) {
+    box.addChild(renderThinkingMarkdown(thinking, theme));
+  }
+  const expandedLines: string[] = [];
+  if (expanded && scout.selectedLabels?.length) {
+    expandedLines.push(
+      theme.fg("dim", `  Selected: ${scout.selectedLabels.join("; ")}`)
+    );
+  }
+  if (expanded && scout.synthesis) {
+    expandedLines.push(
+      theme.fg(
+        "dim",
+        `  Scout synthesis (untrusted inference): ${scout.synthesis}`
+      )
+    );
+  }
+  if (expanded && scout.omittedBeforeScout) {
+    expandedLines.push(
+      theme.fg(
+        "dim",
+        `  ${scout.omittedBeforeScout} group(s) omitted before Scout`
+      )
+    );
+  }
+  if (expandedLines.length > 0) {
+    box.addChild(new Text(expandedLines.join("\n"), 0, 0));
+  }
+};

package/src/tools/session.ts

@@ -0,0 +1,3 @@
+import { AdvisorSessionState } from "../session-state.js";
+
+export const advisorSessionState = new AdvisorSessionState();