pi-advisor-flow 0.1.1 → 0.1.3

package/README.md

@@ -1,5 +1,9 @@
 # pi-advisor
 
+<div align="center">
+<img src="https://raw.githubusercontent.com/philipbrembeck/pi-advisor/refs/heads/main/assets/screenshot.png" alt="Pi Advisor Flow Screenshot" width="600">
+</div>
+
 An on-demand Advisor model flow for autonomous **Pi** coding agents.
 
 This extension introduces a strategic "Executor/Advisor" workflow, inspired by Claudes [Advisor](https://code.claude.com/docs/en/advisor).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-advisor-flow",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -11,7 +11,11 @@
   "main": "extensions/index.ts",
   "types": "extensions/index.ts",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "advisor",
+    "pi-advisor"
   ],
   "files": [
     "extensions",
@@ -21,7 +25,8 @@
   "pi": {
     "extensions": [
       "./extensions/index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/philipbrembeck/pi-advisor/refs/heads/main/assets/hero.png"
   },
   "scripts": {
     "test": "bun test",

package/src/tools.ts

@@ -1,11 +1,14 @@
 import { stream, type Message, type AssistantMessage } from "@earendil-works/pi-ai/compat";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Box, Text } from "@earendil-works/pi-tui";
+import { getMarkdownTheme, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Box, Markdown, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { advisorRef, advisorEffortRef, loadConfig, splitRef } from "./config.js";
 import { recentConversation, textFrom } from "./conversation.js";
 
 export const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export const DEFAULT_ADVISOR_REQUEST = "Review the current task and conversation context. Identify the highest-risk assumption, the smallest correct next step, and any important validation.";
+
+export const resolveAdvisorRequest = (question?: string) => question?.trim() || DEFAULT_ADVISOR_REQUEST;
 
 export const ADVISOR_SYSTEM = [
   "You are the Advisor: a senior engineer consulted by an autonomous coding agent.",
@@ -30,7 +33,7 @@ export const consult = async (
   const conversation = recentConversation(ctx);
   const messages: Message[] = [{
     role: "user",
-    content: [{ type: "text", text: `${conversation ? `<conversation>\n${conversation}\n</conversation>\n\n` : ""}Question from the Executor:\n${question}` }],
+    content: [{ type: "text", text: `${conversation ? `<conversation>\n${conversation}\n</conversation>\n\n` : ""}Request from the Executor:\n${question}` }],
     timestamp: Date.now(),
   }];
 
@@ -71,31 +74,34 @@ export const registerAdvisorTool = (pi: ExtensionAPI) => {
   pi.registerTool({
     name: "ask_advisor",
     label: "Ask Advisor",
-    description: "Consult the on-demand Advisor model for strategic guidance, a second opinion, or a sanity check.",
-    promptSnippet: "Consult the Advisor model for a second opinion",
+    description: "Consult the on-demand Advisor model for strategic guidance, a second opinion, a sanity check, or general contextual advice.",
+    promptSnippet: "Consult the Advisor model for a second opinion or general contextual advice",
     promptGuidelines: [
       "You MUST call `ask_advisor` in each of these scenarios:",
       "1. PLAN GATE: You MUST call `ask_advisor` BEFORE selecting or implementing a plan when multiple materially different approaches exist, requirements are ambiguous, or the decision has architectural, security, data-loss, compatibility, or difficult-to-reverse consequences.",
       "2. FAILURE GATE: You MUST call `ask_advisor` after two consecutive materially equivalent failed attempts, when an attempted fix recreates an earlier failure, or when two consecutive actions produce no measurable progress. Do NOT attempt another materially equivalent fix before consulting.",
       "3. COMPLETION GATE: You MUST call `ask_advisor` with the goal, changed files, key decisions, tests performed, results, and remaining risks BEFORE declaring success or calling `goal_complete`. You MAY skip this only for demonstrably trivial, low-risk work with no meaningful trade-offs or failures.",
+      "For a context-based review without a specific question, call `ask_advisor` with an empty object.",
       "Do NOT use `ask_advisor` for routine decisions outside these three gates.",
     ],
-    parameters: Type.Object({ question: Type.String({ description: "The specific question or decision to get advice on." }) }),
+    parameters: Type.Object({ question: Type.Optional(Type.String({ description: "The specific question or decision to get advice on. Omit for a general contextual review." })) }),
     renderShell: "self",
     renderCall(args, theme, context) {
-      const box = context.lastComponent instanceof Box ? context.lastComponent : new Box(1, 1);
-      box.setBgFn((text) => `\x1b[48;2;25;32;45m${text}\x1b[0m`);
+      const box = context.lastComponent instanceof Box ? context.lastComponent : new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+      box.setBgFn((text) => theme.bg("customMessageBg", text));
       box.clear();
-      if (!context.state.timerId) {
-        context.state.timerId = setInterval(() => context.invalidate(), 80);
-      }
-      const frame = SPINNER_FRAMES[Math.floor(Date.now() / 80) % SPINNER_FRAMES.length];
-      box.addChild(new Text(`${theme.fg("warning", theme.bold(`◆ ADVISOR ${frame}`))} ${theme.fg("dim", `· ${args.question}`)}`, 0, 0));
+      const request = args.question?.trim();
+      const label = theme.fg("customMessageLabel", theme.bold("[advisor]"));
+      const title = theme.fg("customMessageText", "Executor → Advisor");
+      const detail = request
+        ? theme.fg("dim", `  ${request}`)
+        : theme.fg("dim", "  General task review");
+      box.addChild(new Text(`${label} ${title}\n${detail}`, 0, 0));
       return box;
     },
     renderResult(result, { isPartial }, theme, context) {
-      const box = context.lastComponent instanceof Box ? context.lastComponent : new Box(1, 1);
-      box.setBgFn((text) => `\x1b[48;2;25;32;45m${text}\x1b[0m`);
+      const box = context.lastComponent instanceof Box ? context.lastComponent : new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+      box.setBgFn((text) => theme.bg("customMessageBg", text));
       box.clear();
       if (isPartial) {
         if (!context.state.timerId) {
@@ -108,33 +114,36 @@ export const registerAdvisorTool = (pi: ExtensionAPI) => {
           const snippet = d.thinking.length > 200 ? d.thinking.slice(-200) : d.thinking;
           lines.push(theme.fg("thinkingText", `  💭 ${snippet.replace(/\n/g, " ")}`));
         }
-        if (d?.text) lines.push(theme.fg("text", d.text));
         box.addChild(new Text(lines.join("\n"), 0, 0));
+        if (d?.text) box.addChild(new Markdown(d.text, 0, 0, getMarkdownTheme()));
       } else {
         if (context.state.timerId) {
           clearInterval(context.state.timerId);
           delete context.state.timerId;
         }
-        const d = result.details as { thinking?: string; text?: string } | undefined;
-        const lines: string[] = [theme.fg("warning", theme.bold("◆ ADVISOR"))];
+        const d = result.details as { thinking?: string; text?: string; advisor?: string } | undefined;
+        const lines: string[] = [theme.fg("warning", theme.bold("◆ ADVISOR RESPONSE"))];
+        if (d?.advisor) lines.push(theme.fg("dim", `  ${d.advisor}`));
         if (d?.thinking) {
           lines.push(theme.fg("thinkingText", `  💭 ${d.thinking.replace(/\n/g, " ").slice(0, 300)}${d.thinking.length > 300 ? "…" : ""}`));
         }
-        lines.push(textFrom(result.content) || "(Advisor returned no advice.)");
+        const advice = d?.text || textFrom(result.content) || "(Advisor returned no advice.)";
         box.addChild(new Text(lines.join("\n"), 0, 0));
+        box.addChild(new Markdown(advice, 0, 0, getMarkdownTheme()));
       }
       return box;
     },
     async execute(_id, params, signal, onUpdate, ctx) {
-      const { advice, thinkingText } = await consult(ctx, params.question, signal, (t, tx) => {
+      const question = resolveAdvisorRequest(params.question);
+      const { advice, thinkingText } = await consult(ctx, question, signal, (t, tx) => {
         onUpdate?.({
           content: [{ type: "text", text: tx }],
-          details: { thinking: t, text: tx, advisor: advisorRef, question: params.question },
+          details: { thinking: t, text: tx, advisor: advisorRef, question },
         });
       });
       return {
         content: [{ type: "text", text: `Advisor (${advisorRef})\n\n${advice}` }],
-        details: { thinking: thinkingText, text: advice, advisor: advisorRef, question: params.question },
+        details: { thinking: thinkingText, text: advice, advisor: advisorRef, question },
       };
     },
   });