pi-advisor-flow 0.6.0 → 0.8.0

package/extensions/index.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
 import { registerCommands } from "../src/commands/registration.ts";
 import { setHerdrBlockedEmitter } from "../src/herdr.ts";
 import { AdvisorSessionState } from "../src/session-state.ts";
@@ -30,7 +31,7 @@ export const runAdvisorGate = (
   ...args: Parameters<typeof runAdvisorGateImplementation>
 ) => runAdvisorGateImplementation(...args);
 
-export default function (pi: ExtensionAPI) {
+export default function registerPiAdvisor(pi: ExtensionAPI) {
   const sessionState = new AdvisorSessionState();
   const scoutStatus = new ScoutStatusManager();
   setHerdrBlockedEmitter((active, label) =>

package/package.json

@@ -1,25 +1,23 @@
 {
   "name": "pi-advisor-flow",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Advanced Executor/Advisor flow for Pi, fully configurable and extendable.",
   "keywords": [
-    "pi-package",
-    "pi-extension",
-    "pi-coding-agent",
     "advisor",
+    "herdr",
+    "jev",
     "pi-advisor",
-    "herdr"
+    "pi-coding-agent",
+    "pi-extension",
+    "pi-package"
   ],
   "homepage": "https://github.com/philipbrembeck/pi-advisor",
+  "license": "MIT",
+  "author": "Philip Brembeck",
   "repository": {
     "type": "git",
     "url": "https://github.com/philipbrembeck/pi-advisor.git"
   },
-  "license": "MIT",
-  "author": "Philip Brembeck",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "extensions/index.ts",
   "files": [
     "dist",
     "extensions",
@@ -28,6 +26,9 @@
     "LICENSE",
     "README.md"
   ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "extensions/index.ts",
   "scripts": {
     "bench:decisions": "bun bench/src/cli.ts decisions",
     "bench:evaluate": "bun bench/src/cli.ts evaluate",
@@ -35,10 +36,10 @@
     "bench:screen": "bun bench/src/cli.ts screen",
     "build": "bun build ./extensions/index.ts --outfile dist/index.js --target node --format esm --external @earendil-works/pi-ai --external @earendil-works/pi-coding-agent --external @earendil-works/pi-tui --external typebox",
     "check:boundaries": "node scripts/check-module-boundaries.mjs",
-    "format": "bunx ultracite fix --linter-enabled=false",
+    "format": "oxfmt",
     "knip": "knip",
-    "lint": "bunx ultracite check",
-    "lint:fix": "bunx ultracite fix",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
     "prepack": "bun run build >/dev/null",
     "package:check": "node scripts/check-package.mjs",
     "prepare": "husky",
@@ -46,39 +47,30 @@
     "test": "bun test && bun run test:node-loader",
     "test:bench": "bun --config=./bunfig.bench.toml test ./bench/test/",
     "test:node-loader": "node --test test/default-resource-loader.node.mjs",
-    "typecheck": "tsc --noEmit"
-  },
-  "lint-staged": {
-    "*.{json,jsonc,ts}": "bun run lint:fix --"
-  },
-  "resolutions": {
-    "is-unicode-supported": "npm:@socketregistry/is-unicode-supported@1.0.5",
-    "safe-buffer": "npm:@socketregistry/safe-buffer@1.0.9"
-  },
-  "overrides": {
-    "brace-expansion": "5.0.9",
-    "is-unicode-supported": "npm:@socketregistry/is-unicode-supported@1.0.5",
-    "safe-buffer": "npm:@socketregistry/safe-buffer@1.0.9",
-    "undici": "8.9.0"
+    "typecheck": "tsc --noEmit",
+    "format:check": "oxfmt --check"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.12",
-    "@earendil-works/pi-ai": "^0.85.1",
-    "@earendil-works/pi-coding-agent": "^0.85.1",
-    "@earendil-works/pi-tui": "^0.85.1",
-    "@types/node": "^26.4.1",
-    "bun-types": "1.4.1",
+    "@earendil-works/pi-ai": "0.87.1",
+    "@earendil-works/pi-coding-agent": "0.87.1",
+    "@earendil-works/pi-tui": "0.87.1",
+    "@oxlint/plugins": "1.85.0",
+    "@types/node": "^26.6.2",
+    "@typesafe-ai/sdk": "^0.6.0",
+    "bun-types": "1.4.2",
     "husky": "^9.1.7",
-    "knip": "^6.35.1",
-    "lint-staged": "^17.4.1",
-    "typebox": "^1.3.25",
+    "knip": "^6.37.0",
+    "lint-staged": "^17.5.1",
+    "oxfmt": "0.70.0",
+    "oxlint": "1.85.0",
+    "typebox": "^1.3.34",
     "typescript": "^7.0.2",
-    "ultracite": "7.10.8"
+    "ultracite": "7.12.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "^0.84.1 || ^0.85.1",
-    "@earendil-works/pi-coding-agent": "^0.84.1 || ^0.85.1",
-    "@earendil-works/pi-tui": "^0.84.1 || ^0.85.1",
+    "@earendil-works/pi-ai": "^0.85.1 || ^0.87.1",
+    "@earendil-works/pi-coding-agent": "^0.85.1 || ^0.87.1",
+    "@earendil-works/pi-tui": "^0.85.1 || ^0.87.1",
     "typebox": "^1.1.38"
   },
   "peerDependenciesMeta": {
@@ -95,6 +87,29 @@
       "optional": true
     }
   },
+  "resolutions": {
+    "is-unicode-supported": "npm:@socketregistry/is-unicode-supported@1.0.5",
+    "safe-buffer": "npm:@socketregistry/safe-buffer@1.0.9"
+  },
+  "overrides": {
+    "brace-expansion": "5.0.9",
+    "is-unicode-supported": "npm:@socketregistry/is-unicode-supported@1.0.5",
+    "safe-buffer": "npm:@socketregistry/safe-buffer@1.0.9",
+    "undici": "8.9.0"
+  },
+  "lint-staged": {
+    "*.{ts,tsx}": [
+      "oxfmt",
+      "oxlint --fix"
+    ],
+    "{src,test,scripts,tools,extensions}/**/*.{ts,tsx}": [
+      "oxfmt",
+      "oxlint --fix"
+    ],
+    "*.{json,jsonc}": [
+      "oxfmt"
+    ]
+  },
   "pi": {
     "extensions": [
       "./dist/index.js"

package/src/attachments.ts

@@ -2,6 +2,8 @@ import { execFileSync } from "node:child_process";
 import { constants } from "node:fs";
 import { lstat, open, realpath } from "node:fs/promises";
 import { isAbsolute, relative, resolve } from "node:path";
+
+import { isString } from "./content-utils.ts";
 import { redactAndCapText } from "./redaction.ts";
 
 export const ADVISOR_FILE_MAX_BYTES = 8 * 1024;
@@ -12,7 +14,7 @@ export interface UntrackedAttachment {
   text: string;
 }
 
-const PATH_SEGMENTS = /[\\/]/;
+const PATH_SEGMENTS = /[\\/]/u;
 
 const within = (root: string, candidate: string) => {
   const path = relative(root, candidate);
@@ -21,9 +23,9 @@ const within = (root: string, candidate: string) => {
 const normalizeRelativePath = (root: string, path: string) =>
   relative(root, resolve(root, path));
 
-const normalizeRequestedPath = (root: string, value: unknown) => {
+const normalizeRequestedPath = (root: string, value: string) => {
   if (
-    typeof value !== "string" ||
+    !isString(value) ||
     !value ||
     isAbsolute(value) ||
     value.split(PATH_SEGMENTS).includes("..")
@@ -36,7 +38,7 @@ const normalizeRequestedPath = (root: string, value: unknown) => {
 const git = (cwd: string, args: string[]) =>
   execFileSync("git", args, {
     cwd,
-    encoding: "utf8",
+    encoding: "utf-8",
     maxBuffer: 16 * 1024 * 1024,
     shell: false,
     stdio: ["ignore", "pipe", "pipe"],
@@ -48,7 +50,7 @@ const repositoryRoot = (cwd: string) => {
   try {
     return realpath(git(cwd, ["rev-parse", "--show-toplevel"]).trim());
   } catch {
-    return Promise.resolve(undefined);
+    return Promise.resolve();
   }
 };
 
@@ -108,9 +110,9 @@ const readAttachment = async (
   if (!within(root, resolved)) {
     return;
   }
+  // fs.open needs combined numeric flags for O_NOFOLLOW; O_RDONLY (0) and O_NOFOLLOW occupy disjoint bits, so + is exact.
   const flags = constants.O_NOFOLLOW
-    ? // biome-ignore lint/suspicious/noBitwiseOperators: fs.open requires numeric flags for O_NOFOLLOW.
-      constants.O_RDONLY | constants.O_NOFOLLOW
+    ? constants.O_RDONLY + constants.O_NOFOLLOW
     : constants.O_RDONLY;
   const file = await open(resolved, flags);
   try {
@@ -120,13 +122,13 @@ const readAttachment = async (
     }
     const buffer = Buffer.alloc(available + 1);
     const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
-    const raw = buffer.subarray(0, bytesRead).toString("utf8");
+    const raw = buffer.subarray(0, bytesRead).toString("utf-8");
     if (raw.includes("\0")) {
       return;
     }
     const text = redactAndCapText(raw, available, redact);
     return {
-      bytes: Buffer.byteLength(text, "utf8"),
+      bytes: Buffer.byteLength(text, "utf-8"),
       path: normalizedName,
       text,
     };
@@ -169,7 +171,6 @@ const readFiles = async (
         break;
       }
       // Sequentially enforce the aggregate disclosure budget.
-      // biome-ignore lint/performance/noAwaitInLoops: each accepted file consumes the remaining budget.
       const attachment = await readAttachment(
         root,
         normalizedName,

package/src/commands/activation-preparation.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
 import {
   advisorEffortRef,
   advisorRef,

package/src/commands/activation.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
 import { parseArgs } from "../config/args.ts";
 import {
   advisorEffortRef,
@@ -116,6 +117,7 @@ export const activateAdvisor = async (
   // later attempt.
   runtime.pendingExecutorModelRef = undefined;
   if (executorEffortRef) {
+    // SAFETY: executorEffortRef is operator-configured and trusted to name a ThinkingLevel.
     runtime.pi.setThinkingLevel(executorEffortRef as ThinkingLevel);
   }
   if (!runtime.flowEnabled()) {

package/src/commands/lifecycle.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
 import {
   alwaysOnRef,
   executorRef,

package/src/commands/manual-command.ts

@@ -4,11 +4,13 @@ import {
   isSimpleMode,
 } from "../config/state.ts";
 import type { GitContextLevel } from "../git.ts";
+import { advisorModelAccessReason } from "../tools/model-access.ts";
 import { resolveAdvisorRequest } from "../tools/render-common.ts";
 import { ManualAdvisorDialog } from "../ui/manual-dialog.ts";
 import type { ManualAdvisorRequest } from "../ui/types.ts";
 import { loadCommandConfig } from "./activation-preparation.ts";
 import { startManualConsultation } from "./manual-consultation.ts";
+import { notify } from "./runtime.ts";
 import type { CommandRuntime, ManualAdvisorProgressState } from "./types.ts";
 
 export const registerManualCommand = (runtime: CommandRuntime) => {
@@ -19,6 +21,11 @@ export const registerManualCommand = (runtime: CommandRuntime) => {
       if (!loadCommandConfig(ctx)) {
         return;
       }
+      const accessReason = advisorModelAccessReason(ctx);
+      if (accessReason) {
+        notify(ctx, accessReason, "warning");
+        return;
+      }
       if (
         !(
           isSimpleMode() ||
@@ -96,7 +103,6 @@ export const registerManualCommand = (runtime: CommandRuntime) => {
       // Intentional fire-and-forget: the consultation streams after the command
       // handler returns. void satisfies noFloatingPromises; noVoid is ignored here
       // because this Biome version offers no ignoreVoidAsExpression option.
-      // biome-ignore lint/complexity/noVoid: marks an intentional fire-and-forget promise
       void startManualConsultation(
         runtime,
         ctx,

package/src/commands/manual-consultation.ts

@@ -1,14 +1,25 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
 import { advisorRef } from "../config/state.ts";
+import { isString } from "../content-utils.ts";
 import type { GitContextLevel } from "../git.ts";
 import { herdrAdvisorActivity, notifyHerdrAdvisorFailure } from "../herdr.ts";
+import { normalizeScreeningQuestion } from "../tools/jev-filter.ts";
 import { appendScoutLifecycleEntry } from "../tools/scout-status.ts";
 import type { ScoutToolDetails } from "../tools/types.ts";
 import { advisorUsageCost, snapshotAdvisorUsage } from "../usage.ts";
+import type { AdvisorUsageSnapshot } from "../usage.ts";
 import { notify } from "./runtime.ts";
 import type { CommandRuntime, ManualAdvisorProgressState } from "./types.ts";
 
-export const startManualConsultation = (
+interface ManualResultDetails {
+  advisor: string;
+  question?: string;
+  text: string;
+  usage?: AdvisorUsageSnapshot;
+}
+
+export const startManualConsultation = async (
   runtime: CommandRuntime,
   ctx: ExtensionContext,
   question: string | undefined,
@@ -34,8 +45,8 @@ export const startManualConsultation = (
     runtime.manualProgressTimers.set(controller, timer);
   }
   let scoutDetails: ScoutToolDetails | undefined;
-  return runtime
-    .requestAdvisor(
+  try {
+    const { adviceId, markdown, usage } = await runtime.requestAdvisor(
       ctx,
       question,
       controller.signal,
@@ -62,83 +73,96 @@ export const startManualConsultation = (
         }
       },
       gitContext
-    )
-    .then(({ markdown, usage }) => {
-      if (controller.signal.aborted) {
-        return;
-      }
-      progress.phase = "complete";
-      runtime.advisorSessionState.recordInvocation({
-        cost: advisorUsageCost(usage),
-        executionEffect: "continued",
-        kind: "markdown",
-        model: advisorRef,
-        trigger: "manual",
-        usage,
-      });
-      runtime.updateAdvisorUsageStatus(ctx);
-      const normalizedUsage = snapshotAdvisorUsage(usage);
-      runtime.pi.sendMessage(
-        {
-          content: `Manual Advisor consultation${question ? ` (${question})` : ""}:\n\n${markdown}`,
-          customType: "advisor-manual-result",
-          details: {
-            advisor: advisorRef,
-            question,
-            text: markdown,
-            ...(normalizedUsage ? { usage: normalizedUsage } : {}),
-          },
-          display: true,
-        },
-        {
-          // 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;
-      }
-      progress.phase = "error";
-      const message = error instanceof Error ? error.message : String(error);
-      runtime.advisorSessionState.recordInvocation({
-        executionEffect: "continued",
-        failure: "provider-error",
-        kind: "markdown",
-        model: advisorRef,
-        trigger: "manual",
-      });
-      runtime.updateAdvisorUsageStatus(ctx);
-      runtime.pi.sendMessage(
-        {
-          content: `Manual Advisor consultation failed: ${message}`,
-          customType: "advisor-manual-result",
-          details: {
-            advisor: advisorRef,
-            text: `**Advisor consultation failed:** ${message}`,
-          },
-          display: true,
-        },
-        { deliverAs: "steer", triggerTurn: true }
+    );
+    if (controller.signal.aborted) {
+      return;
+    }
+    progress.phase = "complete";
+    runtime.advisorSessionState.resetTurnsSinceConsultation();
+    runtime.advisorSessionState.recordInvocation({
+      cost: advisorUsageCost(usage),
+      executionEffect: "continued",
+      kind: "markdown",
+      model: advisorRef,
+      trigger: "manual",
+      usage,
+    });
+    if (isString(adviceId)) {
+      // Registering the manual question lets an identical later ask_advisor
+      // hit repeat detection instead of re-consulting.
+      runtime.advisorSessionState.issueAdvice(
+        adviceId,
+        markdown,
+        "manual",
+        false,
+        normalizeScreeningQuestion(question)
       );
-      notify(ctx, `Advisor consultation failed: ${message}`, "error");
-      notifyHerdrAdvisorFailure("Advisor consultation failed", message);
-    })
-    .finally(() => {
-      if (controller.signal.aborted) {
-        progress.phase = "cancelled";
-      }
-      const timer = runtime.manualProgressTimers.get(controller);
-      if (timer) {
-        clearInterval(timer);
-        runtime.manualProgressTimers.delete(controller);
+    }
+    runtime.updateAdvisorUsageStatus(ctx);
+    const details: ManualResultDetails = {
+      advisor: advisorRef,
+      question,
+      text: markdown,
+    };
+    const normalizedUsage = snapshotAdvisorUsage(usage);
+    if (normalizedUsage) {
+      details.usage = normalizedUsage;
+    }
+    runtime.pi.sendMessage(
+      {
+        content: `Manual Advisor consultation${question ? ` (${question})` : ""} — for your awareness; no action or follow-up consultation is needed unless the user asks:\n\n${markdown}`,
+        customType: "advisor-manual-result",
+        details,
+        display: true,
+      },
+      {
+        // 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,
       }
-      runtime.requestManualRender(ctx);
-      runtime.scoutStatus.release(ctx, scoutStatusToken);
-      runtime.manualConsultations.delete(controller);
-      herdrAdvisorActivity.finish();
+    );
+  } catch (error) {
+    if (controller.signal.aborted) {
+      return;
+    }
+    progress.phase = "error";
+    const message = error instanceof Error ? error.message : String(error);
+    runtime.advisorSessionState.resetTurnsSinceConsultation();
+    runtime.advisorSessionState.recordInvocation({
+      executionEffect: "continued",
+      failure: "provider-error",
+      kind: "markdown",
+      model: advisorRef,
+      trigger: "manual",
     });
+    runtime.updateAdvisorUsageStatus(ctx);
+    runtime.pi.sendMessage(
+      {
+        content: `Manual Advisor consultation failed: ${message}`,
+        customType: "advisor-manual-result",
+        details: {
+          advisor: advisorRef,
+          text: `**Advisor consultation failed:** ${message}`,
+        },
+        display: true,
+      },
+      { deliverAs: "steer", triggerTurn: true }
+    );
+    notify(ctx, `Advisor consultation failed: ${message}`, "error");
+    notifyHerdrAdvisorFailure("Advisor consultation failed", message);
+  } finally {
+    if (controller.signal.aborted) {
+      progress.phase = "cancelled";
+    }
+    const timer = runtime.manualProgressTimers.get(controller);
+    if (timer) {
+      clearInterval(timer);
+      runtime.manualProgressTimers.delete(controller);
+    }
+    runtime.requestManualRender(ctx);
+    runtime.scoutStatus.release(ctx, scoutStatusToken);
+    runtime.manualConsultations.delete(controller);
+    herdrAdvisorActivity.finish();
+  }
 };

package/src/commands/manual-progress.ts

@@ -1,7 +1,11 @@
-import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
-import { type Component, Markdown, Text } from "@earendil-works/pi-tui";
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Markdown, Text } from "@earendil-works/pi-tui";
+import type { Component } from "@earendil-works/pi-tui";
+
 import {
   adviceForDisplay,
+  noop,
   renderAdvisorCallBox,
   renderThinkingMarkdown,
   SPINNER_FRAMES,
@@ -87,7 +91,5 @@ export class ManualAdvisorProgressComponent implements Component {
     return box.render(width);
   }
 
-  invalidate(): void {
-    // The live progress state is read during each render.
-  }
+  readonly invalidate = noop;
 }

package/src/commands/model-commands.ts

@@ -10,8 +10,8 @@ import {
   setExecutorRef,
 } from "../config/state.ts";
 import { saveConfig } from "../config/storage.ts";
-import { activateAdvisor } from "./activation.ts";
 import { loadCommandConfig } from "./activation-preparation.ts";
+import { activateAdvisor } from "./activation.ts";
 import { selectAdvisorModels } from "./model-picker.ts";
 import type { CommandRuntime } from "./types.ts";
 

package/src/commands/model-options.ts

@@ -1,5 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { type getPersistedModelRefs, splitRef } from "../config/state.ts";
+
+import { splitRef } from "../config/state.ts";
+import type { getPersistedModelRefs } from "../config/state.ts";
 import type { ContextPreset } from "../ui/types.ts";
 
 export const DEFAULT_EFFORT_LEVEL = "Default (Model Default)";
@@ -33,7 +35,7 @@ export const selectedEffort = (choice: string): string | undefined => {
 export const ADVISOR_ACTIVATION_EXPLANATION =
   "The Advisor is a second-opinion model that reviews the Executor's context and returns risks, alternatives, and verification steps without changing files or running tools.";
 
-const ARGUMENT_WHITESPACE = /\s+/;
+const ARGUMENT_WHITESPACE = /\s+/u;
 const hasModelOverride = (args: string, key: "advisor" | "executor") =>
   args
     .trim()
@@ -91,13 +93,14 @@ export const findConfiguredModel = (
     return;
   }
   const [provider, modelId] = splitRef(ref);
+  // oxlint-disable-next-line unicorn/no-array-method-this-argument -- Pi ModelRegistry.find(provider, id), not Array#find.
   return ctx.modelRegistry.find(provider, modelId);
 };
 
 export const getAvailableModelRefs = (
   ctx: ExtensionContext
 ): string[] | undefined => {
-  if (typeof ctx.modelRegistry.getAvailable !== "function") {
+  if (!ctx.modelRegistry.getAvailable) {
     return undefined;
   }
   return ctx.modelRegistry
@@ -105,6 +108,14 @@ export const getAvailableModelRefs = (
     .map((model) => `${model.provider}/${model.id}`);
 };
 
+export const getConfiguredModelRefs = (ctx: ExtensionContext): string[] => {
+  const registry = ctx.modelRegistry;
+  const models = registry?.getAvailable ? registry.getAvailable() : [];
+  return [
+    ...new Set(models.map((model) => `${model.provider}/${model.id}`)),
+  ].toSorted((left, right) => left.localeCompare(right));
+};
+
 const isSelectableModel = (
   ctx: ExtensionContext,
   ref: string | undefined,

package/src/commands/model-picker.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
 import { SearchableModelSelector } from "../ui/model-selector.ts";
 import {
   effortChoices,

package/src/commands/registration.ts

@@ -2,6 +2,7 @@ import type {
   ExtensionAPI,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+
 import { activateAdvisor } from "./activation.ts";
 import { registerCommandLifecycle } from "./lifecycle.ts";
 import { registerManualCommand } from "./manual-command.ts";