pi-advisor-flow 0.1.1 → 0.1.4

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).
@@ -39,6 +43,7 @@ Once installed, the following commands are available inside the Pi terminal:
 Enables the Advisor flow. Switches the primary model to the configured Executor model and registers the `ask_advisor` tool.
 
 - _Example:_ `/advisor executor=anthropic/claude-sonnet-5 advisor=openai/gpt-5.6-sol`
+- _Context size:_ `/advisor contextMaxChars=30000` uses up to 30,000 characters of the reconstructed conversation for each consultation. The default is 15,000; the maximum is 1,000,000. Larger values increase request cost and can exceed the advisor model's context window.
 
 ### `/advisor-models`
 
@@ -49,6 +54,22 @@ Opens an interactive, scrollable fuzzy-search picker in the TUI to choose:
 
 Saves and persists your configuration to `~/.pi/agent/advisor.json`.
 
+### `ask_advisor`
+
+The Executor can call `ask_advisor` with an empty object for a general review of the current task and conversation, or provide `question` for targeted feedback. The Advisor is a brief second opinion: the Executor investigates and forms its own candidate direction first, then uses the Advisor to challenge assumptions and validate a consequential next step. It should not delegate the entire plan or task.
+
+### Context configuration
+
+The selected configuration is saved as `advisor.json` in the Pi agent directory (or an existing trusted project configuration). Set `contextMaxChars` there to increase the reconstructed conversation limit for all consultations:
+
+```json
+{
+  "contextMaxChars": 30000
+}
+```
+
+`contextMaxChars` must be a positive integer up to 1,000,000. Its default is 15,000.
+
 ### `/advisor-off`
 
 Disables the Advisor flow, removing the `ask_advisor` tool from the active session.

package/package.json

@@ -1,17 +1,23 @@
 {
   "name": "pi-advisor-flow",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com/philipbrembeck/pi-advisor.git"
   },
+  "homepage": "https://github.com/philipbrembeck/pi-advisor",
+  "author": "Philip Brembeck",
   "description": "Executor/Advisor flow for autonomous pi coding agents",
   "type": "module",
   "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 +27,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/commands.ts

@@ -12,10 +12,14 @@ export const registerCommands = (pi: ExtensionAPI) => {
   const flowEnabled = () => pi.getActiveTools().includes("ask_advisor");
 
   pi.registerCommand("advisor", {
-    description: "Enable the Executor/Advisor flow and switch to the configured Executor model",
+    description: "Enable the Executor/Advisor flow and switch to the configured Executor model; accepts contextMaxChars=N",
     handler: async (args, ctx) => {
       loadConfig(ctx);
-      parseArgs(args);
+      const argumentError = parseArgs(args);
+      if (argumentError) {
+        if (ctx.hasUI) ctx.ui.notify(argumentError, "error");
+        return;
+      }
       const [provider, modelId] = splitRef(executorRef);
       const executor = ctx.modelRegistry.find(provider, modelId);
       if (!executor) return ctx.hasUI ? ctx.ui.notify(`Executor model not found: ${executorRef}`, "error") : undefined;

package/src/config.ts

@@ -4,16 +4,22 @@ import { CONFIG_DIR_NAME, type ExtensionContext, getAgentDir } from "@earendil-w
 
 export const FALLBACK_EXECUTOR = "aikeys/claude-sonnet-5";
 export const FALLBACK_ADVISOR = "aikeys/claude-fable-5";
+export const DEFAULT_CONTEXT_MAX_CHARS = 15_000;
+export const MAX_CONTEXT_MAX_CHARS = 1_000_000;
 
 export let executorRef = FALLBACK_EXECUTOR;
 export let advisorRef = FALLBACK_ADVISOR;
 export let executorEffortRef: string | undefined = undefined;
 export let advisorEffortRef: string | undefined = undefined;
+export let contextMaxCharsRef = DEFAULT_CONTEXT_MAX_CHARS;
 
 export const setExecutorRef = (ref: string) => { executorRef = ref; };
 export const setAdvisorRef = (ref: string) => { advisorRef = ref; };
 export const setExecutorEffortRef = (effort: string | undefined) => { executorEffortRef = effort; };
 export const setAdvisorEffortRef = (effort: string | undefined) => { advisorEffortRef = effort; };
+export const isValidContextMaxChars = (value: unknown): value is number =>
+  typeof value === "number" && Number.isSafeInteger(value) && value > 0 && value <= MAX_CONTEXT_MAX_CHARS;
+export const setContextMaxCharsRef = (value: number) => { contextMaxCharsRef = value; };
 
 export const splitRef = (ref: string): [string, string] => {
   const i = ref.indexOf("/");
@@ -30,6 +36,7 @@ export const loadConfig = (ctx: ExtensionContext) => {
   advisorRef = FALLBACK_ADVISOR;
   executorEffortRef = undefined;
   advisorEffortRef = undefined;
+  contextMaxCharsRef = DEFAULT_CONTEXT_MAX_CHARS;
   for (const path of configPaths(ctx)) {
     if (!path || !existsSync(path)) continue;
     try {
@@ -38,11 +45,13 @@ export const loadConfig = (ctx: ExtensionContext) => {
         advisor?: string;
         executorEffort?: string;
         advisorEffort?: string;
+        contextMaxChars?: number;
       };
       if (config.executor) executorRef = config.executor;
       if (config.advisor) advisorRef = config.advisor;
       if (config.executorEffort) executorEffortRef = config.executorEffort;
       if (config.advisorEffort) advisorEffortRef = config.advisorEffort;
+      if (isValidContextMaxChars(config.contextMaxChars)) contextMaxCharsRef = config.contextMaxChars;
       return path;
     } catch {
       // Ignore malformed config and keep looking for a valid fallback.
@@ -59,15 +68,32 @@ export const saveConfig = (ctx: ExtensionContext) => {
     advisor: advisorRef,
     executorEffort: executorEffortRef,
     advisorEffort: advisorEffortRef,
+    contextMaxChars: contextMaxCharsRef,
   };
   writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`);
   return path;
 };
 
-export const parseArgs = (args: string) => {
+export const parseArgs = (args: string): string | undefined => {
+  let nextExecutor = executorRef;
+  let nextAdvisor = advisorRef;
+  let nextContextMaxChars = contextMaxCharsRef;
+
   for (const token of args.trim().split(/\s+/).filter(Boolean)) {
     const [key, value] = token.split("=");
-    if (key === "executor" && value) executorRef = value;
-    if (key === "advisor" && value) advisorRef = value;
+    if (key === "executor" && value) nextExecutor = value;
+    if (key === "advisor" && value) nextAdvisor = value;
+    if (key === "contextMaxChars") {
+      const parsed = Number(value);
+      if (!isValidContextMaxChars(parsed)) {
+        return `contextMaxChars must be a positive integer no greater than ${MAX_CONTEXT_MAX_CHARS}.`;
+      }
+      nextContextMaxChars = parsed;
+    }
   }
+
+  executorRef = nextExecutor;
+  advisorRef = nextAdvisor;
+  contextMaxCharsRef = nextContextMaxChars;
+  return undefined;
 };

package/src/tools.ts

@@ -1,16 +1,19 @@
 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 { advisorRef, advisorEffortRef, contextMaxCharsRef, 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.",
-  "You do not act — you advise. Give concise, high-signal guidance: identify risks,",
-  "the smallest correct next step, and wrong assumptions. No preamble.",
+  "You are the Advisor: a senior engineer giving a brief second opinion to an autonomous coding agent.",
+  "You do not act or take over planning. Help the Executor validate its own proposed direction:",
+  "identify risks, challenge assumptions, and recommend the smallest correct next step. No preamble.",
 ].join(" ");
 
 export const consult = async (
@@ -27,10 +30,10 @@ export const consult = async (
   if (!auth.ok) throw new Error((auth as { error: string }).error);
   if (!auth.apiKey) throw new Error(`No API key for ${advisorRef}`);
 
-  const conversation = recentConversation(ctx);
+  const conversation = recentConversation(ctx, contextMaxCharsRef);
   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,31 @@ 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. Call with no arguments for a general review of the current task and conversation, or provide question for targeted advice.",
+    promptSnippet: "Consult the Advisor for targeted advice, or call with no arguments for a general task and conversation review",
     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.",
+      "1. PLAN GATE: Before committing to a materially consequential plan, first investigate and form your own candidate direction. Then call `ask_advisor` to stress-test the decision when multiple approaches exist, requirements are ambiguous, or the decision has architectural, security, data-loss, compatibility, or difficult-to-reverse consequences. Do not delegate the whole plan or task to the Advisor.",
       "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.",
+      "Call `ask_advisor` with an empty object for a general review of the current task and conversation. Provide `question` when you want the Advisor to assess a specific assumption, trade-off, or proposed next step.",
       "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");
+      box.addChild(new Text(request ? `${label} ${title}\n${theme.fg("dim", `  ${request}`)}` : `${label} ${title}`, 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 +111,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 },
       };
     },
   });