pi-advisor-flow 0.1.5 → 0.1.7

package/README.md

@@ -45,6 +45,10 @@ Enables the Advisor flow. Switches the primary model to the configured Executor
 - _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. `0` disables history; `Number.MAX_SAFE_INTEGER` represents the complete branch. Larger values increase request cost and can exceed the Advisor model's context window.
 
+### `/advisor-manual [focus]`
+
+Starts an Advisor consultation in parallel without interrupting the Executor's active tool work. An optional `focus` is passed to the Advisor; when it completes, the advice is delivered to the Executor before its next model call. This works while the Executor is mid-turn.
+
 ### `/advisor-settings`
 
 Opens a single keyboard-navigable settings screen. It includes a Claude Code-style context slider with `0`, `10k`, `25k`, `100k`, `200k`, and `ALL`; `0` sends no reconstructed history and `ALL` sends the complete current branch, subject to the Advisor model's context limit.
@@ -89,6 +93,13 @@ All fields are optional. `executor`, `advisor`, and their effort settings are ma
 
 Disables the Advisor flow, removing the `ask_advisor` tool from the active session.
 
+## Publishing releases
+
+Pushing a version tag (`vX.Y.Z`) runs the release workflow. It verifies that the tag matches `package.json`, type-checks, tests, then publishes:
+
+- `pi-advisor-flow` to [npm](https://www.npmjs.com/package/pi-advisor-flow)
+- `@philipbrembeck/pi-advisor-flow` to GitHub Packages, which makes the package appear in this repository’s **Packages** sidebar
+
 ## Local Development
 
 `pi-advisor` uses Bun for rapid testing and TypeScript. Standard commands apply:
@@ -112,5 +123,5 @@ Verify code-splitting correctness and registration logic:
 
 ```bash
 bun test            # Run unit tests
-npm run typecheck   # Perform strict TS checks
+bun run typecheck   # Perform strict TS checks
 ```

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "pi-advisor-flow",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/philipbrembeck/pi-advisor.git"
+    "url": "https://github.com/philipbrembeck/pi-advisor.git"
   },
   "homepage": "https://github.com/philipbrembeck/pi-advisor",
   "author": "Philip Brembeck",

package/src/commands.ts

@@ -1,4 +1,5 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getMarkdownTheme, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Box, Markdown, Text } from "@earendil-works/pi-tui";
 import {
   advisorCollapseResponsesRef, advisorCompletionGateRef, advisorCustomInvocationRef, advisorFailureGateRef, advisorPlanGateRef,
   advisorRef, advisorEffortRef, executorRef, executorEffortRef,
@@ -7,6 +8,8 @@ import {
   contextMaxCharsRef, loadConfig, saveConfig, parseArgs, splitRef,
 } from "./config.js";
 import { AdvisorSettingsSelector, SearchableModelSelector, type AdvisorSettings, type ContextPreset } from "./ui.js";
+import { herdrAdvisorActivity } from "./herdr.js";
+import { adviceForDisplay, consult, renderAdvisorCallBox, resolveAdvisorRequest } from "./tools.js";
 
 const EFFORT_LEVELS = ["Default (Model Default)", "off", "minimal", "low", "medium", "high", "xhigh", "max"];
 
@@ -19,8 +22,71 @@ const CONTEXT_PRESETS: ContextPreset[] = [
   { label: "ALL", value: Number.MAX_SAFE_INTEGER, description: "The complete reconstructed conversation branch. Cost and model context limits apply." },
 ];
 
-export const registerCommands = (pi: ExtensionAPI) => {
+export const registerCommands = (pi: ExtensionAPI, dependencies: { consult?: typeof consult } = {}) => {
   const flowEnabled = () => pi.getActiveTools().includes("ask_advisor");
+  const requestAdvisor = dependencies.consult ?? consult;
+  const manualConsultations = new Set<AbortController>();
+
+  pi.registerEntryRenderer?.("advisor-manual-call", (entry, _options, theme) => {
+    const { question } = (entry.data ?? {}) as { question?: string };
+    return renderAdvisorCallBox(question, theme);
+  });
+
+  pi.registerMessageRenderer?.("advisor-manual-result", (message, { expanded }, theme) => {
+    const details = message.details as { advisor?: string; text?: string } | undefined;
+    const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+    box.addChild(new Text(theme.fg("warning", theme.bold("◆ ADVISOR RESPONSE")), 0, 0));
+    if (details?.advisor) box.addChild(new Text(theme.fg("dim", `  ${details.advisor}`), 0, 0));
+    const advice = details?.text ?? (typeof message.content === "string" ? message.content : "(Advisor returned no advice.)");
+    box.addChild(new Markdown(adviceForDisplay(advice, expanded), 0, 0, getMarkdownTheme()));
+    return box;
+  });
+
+  pi.on("session_shutdown", () => {
+    for (const controller of manualConsultations) controller.abort();
+    manualConsultations.clear();
+    herdrAdvisorActivity.clear();
+  });
+
+  pi.registerCommand("advisor-manual", {
+    description: "Consult the Advisor in parallel; accepts an optional focused question and fans its response out to the Executor",
+    handler: async (args, ctx) => {
+      const question = resolveAdvisorRequest(args);
+      // A single visible progress surface avoids competing consultations overwriting
+      // each other's streamed state. A newer manual request replaces the previous one.
+      for (const pending of manualConsultations) pending.abort();
+      manualConsultations.clear();
+      const controller = new AbortController();
+      manualConsultations.add(controller);
+      pi.appendEntry?.("advisor-manual-call", { question });
+
+      herdrAdvisorActivity.start();
+      void requestAdvisor(ctx, question, controller.signal)
+        .then(({ advice }) => {
+          if (controller.signal.aborted) return;
+          pi.sendMessage({
+            customType: "advisor-manual-result",
+            content: `Manual Advisor consultation${question ? ` (${question})` : ""}:\n\n${advice}`,
+            display: true,
+            details: { advisor: advisorRef, question, text: advice },
+          }, {
+            // Steer lets the current turn finish its active work; the Executor sees
+            // the result before its next model call rather than being interrupted.
+            deliverAs: "steer",
+            triggerTurn: true,
+          });
+        })
+        .catch((error: unknown) => {
+          if (controller.signal.aborted) return;
+          const message = error instanceof Error ? error.message : String(error);
+          if (ctx.hasUI) ctx.ui.notify(`Advisor consultation failed: ${message}`, "error");
+        })
+        .finally(() => {
+          manualConsultations.delete(controller);
+          herdrAdvisorActivity.finish();
+        });
+    },
+  });
 
   pi.registerCommand("advisor", {
     description: "Enable the Executor/Advisor flow and switch to the configured Executor model; accepts contextMaxChars=N",

package/src/herdr.ts

@@ -0,0 +1,87 @@
+import net from "node:net";
+
+const SOURCE = "pi-advisor:advisor-activity";
+const HERDR_PI_SOURCE = "herdr:pi";
+let sequence = Date.now() * 1_000;
+
+const nextSequence = () => ++sequence;
+
+type HerdrRequest = {
+  id: string;
+  method: "pane.report_metadata";
+  params: {
+    pane_id: string;
+    source: string;
+    agent: "pi";
+    applies_to_source: string;
+    state_labels?: { working: string };
+    clear_state_labels?: true;
+    seq: number;
+  };
+};
+
+type Report = (request: HerdrRequest) => void;
+
+const sendToHerdr: Report = (request) => {
+  if (process.env.HERDR_ENV !== "1") return;
+  const paneId = process.env.HERDR_PANE_ID;
+  const socketPath = process.env.HERDR_SOCKET_PATH;
+  if (!paneId || !socketPath) return;
+
+  const endpoint = process.platform === "win32" ? `\\\\.\\pipe\\${socketPath}` : socketPath;
+  const socket = net.createConnection(endpoint);
+  const timeout = setTimeout(() => socket.destroy(), 500);
+  timeout.unref?.();
+  socket.once("connect", () => socket.write(`${JSON.stringify(request)}\n`));
+  socket.once("data", () => socket.destroy());
+  socket.once("error", () => socket.destroy());
+  socket.once("close", () => clearTimeout(timeout));
+};
+
+export class HerdrAdvisorActivity {
+  #activeConsultations = 0;
+
+  constructor(private readonly report: Report = sendToHerdr) {}
+
+  start() {
+    this.#activeConsultations += 1;
+    if (this.#activeConsultations === 1) this.safeReport(false);
+  }
+
+  finish() {
+    if (this.#activeConsultations === 0) return;
+    this.#activeConsultations -= 1;
+    if (this.#activeConsultations === 0) this.safeReport(true);
+  }
+
+  clear() {
+    if (this.#activeConsultations === 0) return;
+    this.#activeConsultations = 0;
+    this.safeReport(true);
+  }
+
+  private safeReport(clear: boolean) {
+    try {
+      this.report(this.request(clear));
+    } catch {
+      // Herdr is optional; an unavailable integration must never affect advice.
+    }
+  }
+
+  private request(clear: boolean): HerdrRequest {
+    return {
+      id: `${SOURCE}:${nextSequence()}`,
+      method: "pane.report_metadata",
+      params: {
+        pane_id: process.env.HERDR_PANE_ID ?? "",
+        source: SOURCE,
+        agent: "pi",
+        applies_to_source: HERDR_PI_SOURCE,
+        ...(clear ? { clear_state_labels: true } : { state_labels: { working: "seeking advice" } }),
+        seq: nextSequence(),
+      },
+    };
+  }
+}
+
+export const herdrAdvisorActivity = new HerdrAdvisorActivity();

package/src/tools.ts

@@ -7,12 +7,21 @@ import {
   advisorRef, advisorEffortRef, contextMaxCharsRef, loadConfig, splitRef,
 } from "./config.js";
 import { recentConversation, textFrom } from "./conversation.js";
+import { herdrAdvisorActivity } from "./herdr.js";
 
 export const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 export const resolveAdvisorRequest = (question?: string) => question?.trim() || undefined;
 export const advisorMessageText = (conversation: string, question?: string) =>
   `${conversation ? `<conversation>\n${conversation}\n</conversation>` : ""}${question ? `\n\nTargeted focus:\n${question}` : ""}`;
 
+export const renderAdvisorCallBox = (question: string | undefined, theme: any) => {
+  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;
 
 export const adviceForDisplay = (advice: string, expanded: boolean) => {
@@ -112,15 +121,8 @@ export const registerAdvisorTool = (pi: ExtensionAPI) => {
     ],
     parameters: Type.Object({ question: Type.Optional(Type.String({ description: "The specific question or decision to get advice on. Omit this for normal reviews: the Advisor already has the conversation context." })) }),
     renderShell: "self",
-    renderCall(args, theme, context) {
-      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();
-      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;
+    renderCall(args, theme, _context) {
+      return renderAdvisorCallBox(args.question?.trim(), theme);
     },
     renderResult(result, { isPartial, expanded }, theme, context) {
       const box = context.lastComponent instanceof Box ? context.lastComponent : new Box(1, 1, (text) => theme.bg("customMessageBg", text));
@@ -158,16 +160,21 @@ export const registerAdvisorTool = (pi: ExtensionAPI) => {
     },
     async execute(_id, params, signal, onUpdate, ctx) {
       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 },
+      herdrAdvisorActivity.start();
+      try {
+        const { advice, thinkingText } = await consult(ctx, question, signal, (t, tx) => {
+          onUpdate?.({
+            content: [{ type: "text", text: tx }],
+            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 },
-      };
+        return {
+          content: [{ type: "text", text: `Advisor (${advisorRef})\n\n${advice}` }],
+          details: { thinking: thinkingText, text: advice, advisor: advisorRef, question },
+        };
+      } finally {
+        herdrAdvisorActivity.finish();
+      }
     },
   });
 };