@hk_net/pi-advisor 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.9 - 2026-08-23
+
+### Changed
+
+- Add the copyright holder and EUPL licensing notice to the package license and canonical TypeScript source.
+- Identify KAPPER NETWORK-COMMUNICATIONS GmbH and kapper.net in the npm author metadata.
+
+## 0.1.8 - 2026-08-23
+
+### Changed
+
+- Mark Pi's host-provided SDK packages as optional wildcard peers so npm does not install a redundant Pi SDK dependency tree.
+- Verify development and tests against Pi SDK 0.84.2 while retaining runtime compatibility with Pi 0.84.1 and newer.
+- Refine advisor tool guidance so non-trivial tasks require a review at an evidence-backed checkpoint before the final answer without encouraging an immediate first-action call.
+- Make reviewer responses checkpoint-aware, evidence-grounded, and limited to a verdict plus three prioritized actions.
+- Prevent `/advisor` from writing project-scoped configuration until Pi trusts the project.
+- Run `onDone` review only after Pi fully settles retries, compaction recovery, and queued continuations.
+- Write advisor configuration atomically with owner-only file permissions where supported.
+- Document that the individual package and GitHub bundle must not be installed together.
+
 ## 0.1.7 - 2026-08-13
 
 ### Changed

package/LICENSE

@@ -1,3 +1,6 @@
+Copyright © 2026 kapper.net - KAPPER NETWORK-COMMUNICATIONS GmbH
+Licensed under the EUPL
+
                       EUROPEAN UNION PUBLIC LICENCE v. 1.2
                       EUPL © the European Union 2007, 2016
 

package/README.md

@@ -1,6 +1,6 @@
 # pi-advisor
 
-A [pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) extension for pi `>=0.84.1` that offers a
+A [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) extension for Pi 0.84.1 or newer (tested with the current Pi 0.84.2 release) that offers a
 parameterless `advisor` tool — inspired by Claude Code's advisor, but expanded with additional
 nudges and a manual review procedure. The regular model calls `advisor` to get a second opinion
 from an explicitly configured **stronger reviewer model** that sees the *entire* conversation transcript. Beyond the
@@ -11,24 +11,33 @@ or finishes a task, and the human can invoke a manual review via `/advise`.
 
 When the model calls `advisor` (no arguments), the extension serializes the full active branch —
 user/assistant text, assistant **reasoning**, every **tool call (with args)** and its **result** —
-and forwards it to a stronger reviewer model with a reviewer system prompt. The reviewer returns
-direct, actionable advice (flag wrong assumptions, name what's likely to bite, scrutinize "I'm
-done" claims). Individual tool-call arguments are truncated at 800 characters and tool results at
+and forwards it to a stronger reviewer model with a reviewer system prompt. The reviewer infers whether it is assessing a plan,
+a concrete failure, or claimed completion; checks the work against user and repository instructions
+and primary-source evidence; and returns a verdict plus at most three prioritized actions. A
+premature consultation asks for the specific missing evidence instead of inventing a verdict.
+Individual tool-call arguments are truncated at 800 characters and tool results at
 2,000 characters so huge outputs do not dominate the review; after that, the transcript is truncated
 oldest-first only if it would overflow the reviewer's context window.
 
 Beyond the callable tool, the extension provides two additional ways to get advice:
 
-- **Automatic nudges** — the tool's `promptGuidelines` encourage the model to call advisor
-  *before substantive work*, *when stuck*, and *when it believes the task is complete*. Two
-  opt-in deterministic triggers (`onDone`, `whenStuck`) go further: they auto-consult the
-  reviewer and inject the feedback directly into the conversation so the agent sees it.
+- **Automatic nudges** — the tool's `promptGuidelines` tell the model to call advisor at a
+  useful checkpoint in every non-trivial task: after enough investigation to form an
+  evidence-backed approach and before a consequential edit, when stuck, or after implementation
+  and verification before claiming completion. A mandatory pre-final check tells the model not to
+  finish non-trivial work unless it has called advisor at least once after gathering evidence.
+  The guidance explicitly prohibits an advisor call as the first action or while there is no
+  substantive evidence or work to review. Two opt-in
+  deterministic triggers (`onDone`, `whenStuck`) go further: they auto-consult the reviewer and
+  inject the feedback directly into the conversation so the agent sees it.
 - **Manual review via `/advise`** — the human can invoke a one-off review at any time. Feedback
   can be shown UI-only (informal, for the human), piped into the chat as a user message, or
   injected as a steering message so the running agent sees and acts on it.
 
 ## Files & install
 
+> **Avoid duplicate installation.** Install this npm package or the GitHub bundle, not both. Loading both copies can duplicate tools, commands, and automatic event handlers.
+
 - `advisor.ts` — canonical source (this repo).
 - Package-installed copy: loaded from this package's `pi.extensions` manifest after `pi install`.
 
@@ -118,8 +127,9 @@ Autocomplete completes `/adviso...` to `/advisor` without Pi's trailing-space in
 Default **off** — out of the box the regular model decides when to call `advisor`, nudged by the
 tool's `promptGuidelines`. Two opt-in deterministic triggers, configurable per project and global:
 
-- **`onDone`** — on `agent_end`, auto-review and steer one follow-up so the agent addresses any
-  issues before truly stopping (guarded to at most once per user prompt).
+- **`onDone`** — on `agent_settled`, after automatic retries, compaction recovery, and queued
+  continuations finish, auto-review and steer one follow-up so the agent addresses any issues
+  before truly stopping (guarded to at most once per user prompt).
 - **`whenStuck: N`** — after N consecutive tool errors **or** N repeated identical tool calls
   (same tool name + same arguments), auto-consult the reviewer and inject the advice as a
   steering message to get unstuck.
@@ -131,7 +141,8 @@ tool's `promptGuidelines`. Two opt-in deterministic triggers, configurable per p
   another model.
 - **Project config follows pi project trust.** A global install ignores `<cwd>/.pi/advisor.json`
   while the current project is untrusted, so an untrusted checkout cannot silently choose a reviewer
-  model or enable auto-triggers.
+  model or enable auto-triggers. `/advisor` also withholds the project scope from its configuration
+  picker until the project is trusted; global configuration remains available.
 - **Auto-triggers are off by default.** The `onDone` and `whenStuck` features must be explicitly
   enabled in configuration, and they do nothing unless a reviewer model is configured.
 - **Data sent to the reviewer model.** When `advisor` is called, the extension sends the full

package/advisor.ts

@@ -1,3 +1,6 @@
+// Copyright © 2026 kapper.net - KAPPER NETWORK-COMMUNICATIONS GmbH
+// SPDX-License-Identifier: EUPL-1.2
+
 /**
  * advisor.ts — a pi extension inspired by Claude Code's `advisor` tool, expanded
  * with automatic triggers and a human-invoked manual review command.
@@ -44,7 +47,7 @@ import { getSupportedThinkingLevels, Type } from "@earendil-works/pi-ai";
 import type { Api, Model, ModelThinkingLevel, ProviderHeaders } from "@earendil-works/pi-ai";
 import { complete } from "@earendil-works/pi-ai/compat";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { CONFIG_DIR_NAME, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import { Box, Markdown, SelectList, truncateToWidth } from "@earendil-works/pi-tui";
 import type { AutocompleteItem, Component } from "@earendil-works/pi-tui";
 import * as fs from "node:fs";
@@ -193,19 +196,28 @@ tool outputs, file contents, command output, or other transcript excerpts unless
 are directly relevant to reviewing the coding agent's work. Do not quote secrets or
 credentials unless strictly necessary to identify a concrete issue.
 
+First infer the checkpoint: evidence gathering or plan review, recovery from a
+concrete failure, or completion review. Judge the work appropriate to that checkpoint.
+If the transcript is too early to support a useful review, say that plainly and name
+the specific evidence the agent should gather next; do not invent a verdict.
+
 Give direct, high-signal advice. Specifically:
+- Check the user's actual goal, repository instructions, primary-source API evidence,
+  and existing project patterns before endorsing the approach.
 - If the agent is about to build on a wrong assumption, a misread of a file, or a
   flawed interpretation of the request, say so plainly and point at the evidence.
 - If the approach is sound, confirm it and name the one or two things most likely to
   bite — edge cases, missed requirements, or unverified claims.
-- If the agent thinks it is done, scrutinize that: is there a requirement left unmet,
-  a claim asserted but not verified, a test that doesn't actually test the change?
+- If the agent thinks it is done, scrutinize the actual changes and verification: is
+  a requirement left unmet, a claim unverified, or a test not exercising the behavior?
+  Do not manufacture unrelated scope or demand changes unsupported by the task.
 - Prefer concrete next actions over generic best-practice lectures. Cite specific
-  files, functions, or transcript moments.
+  files, functions, commands, or transcript moments.
 
-Be concise and decisive. You are the more capable model in the room — act like it.
-Do not restate the transcript back; the agent already has it. Lead with your verdict.
-Always return your advice as visible assistant text. Do not return reasoning-only output.`;
+Be concise and decisive. Lead with a one-sentence verdict, followed by at most three
+prioritized actions. If no corrective action is needed, say the work is ready and name
+only any final verification still warranted. Do not restate the transcript back; the
+agent already has it. Always return visible assistant text, never reasoning-only output.`;
 
 // ── Config files ────────────────────────────────────────────────────────────
 
@@ -218,7 +230,14 @@ type AdvisorConfig = {
 };
 
 const globalConfigPath = () => path.join(os.homedir(), ".pi", "agent", "advisor.json");
-const projectConfigPath = (cwd: string) => path.join(cwd, ".pi", "advisor.json");
+const projectConfigPath = (cwd: string) => path.join(cwd, CONFIG_DIR_NAME, "advisor.json");
+
+const PROJECT_SCOPE = "This folder (project)";
+const GLOBAL_SCOPE = "Global (all projects)";
+
+export function getAdvisorScopeChoices(projectTrusted: boolean): string[] {
+  return projectTrusted ? [PROJECT_SCOPE, GLOBAL_SCOPE] : [GLOBAL_SCOPE];
+}
 
 export function validateAdvisorConfig(raw: unknown, source = "advisor config"): AdvisorConfig {
   const warn = (message: string) => console.warn(`[pi-advisor] Ignoring invalid ${source}: ${message}`);
@@ -282,7 +301,14 @@ function writeConfig(file: string, cfg: AdvisorConfig): void {
   if (cfg.onDone !== undefined) clean.onDone = cfg.onDone;
   if (cfg.whenStuck !== undefined) clean.whenStuck = cfg.whenStuck;
   if (cfg.timeoutMs !== undefined) clean.timeoutMs = cfg.timeoutMs;
-  fs.writeFileSync(file, JSON.stringify(clean, null, 2) + "\n", "utf-8");
+
+  const temporaryFile = `${file}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    fs.writeFileSync(temporaryFile, JSON.stringify(clean, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
+    fs.renameSync(temporaryFile, file);
+  } finally {
+    fs.rmSync(temporaryFile, { force: true });
+  }
 }
 
 // ── Resolution ──────────────────────────────────────────────────────────────
@@ -797,14 +823,16 @@ export default function advisorExtension(pi: ExtensionAPI) {
     label: "Advisor",
     description:
       "Consult a configured stronger reviewer model that sees your full conversation transcript. " +
-      "Takes NO parameters — if a reviewer model is configured, the entire active conversation " +
-      "(your task, reasoning, every tool call and result) is forwarded automatically. " +
-      "If no reviewer model is configured, this sends nothing and returns setup guidance. " +
-      "Returns direct, actionable advice.",
-    promptSnippet: "Consult a configured stronger reviewer model on the full transcript before/after substantive work",
+      "Use it only after the transcript contains substantive investigation, an evidence-backed plan, " +
+      "implementation work, or a concrete failure to review; do not call it as the first action. " +
+      "Takes NO parameters — if configured, the entire active conversation (task, reasoning, tool calls, " +
+      "and results) is forwarded automatically. If unconfigured, it sends nothing and returns setup guidance.",
+    promptSnippet: "Mandatory evidence-based review checkpoint for non-trivial work; never the first action",
     promptGuidelines: [
-      "Call advisor before substantive work (before writing, before committing to an interpretation or assumption), when stuck (errors recurring, approach not converging), and when you believe the task is complete.",
-      "advisor takes no arguments; if no reviewer model is configured, it sends nothing and returns setup guidance. Otherwise it forwards the whole conversation. Give its advice serious weight, but if a concrete step it suggests fails empirically or contradicts primary-source evidence you hold, adapt rather than follow blindly.",
+      "For every non-trivial task, you MUST call advisor at a useful checkpoint: after investigating enough context to form an evidence-backed approach and before the first consequential edit, when concrete failures recur or the approach stops converging, or after implementation and verification before claiming completion.",
+      "Before giving a final answer on any non-trivial task, verify that you called advisor at least once after gathering substantive evidence. If you have not, call advisor now and incorporate its result; do not finish the task without this review.",
+      "Never call advisor as the first action, merely to restate the user's request, or while the transcript contains no substantive evidence or work for a reviewer to assess. Trivial questions and mechanical edits do not require advisor.",
+      "advisor takes no arguments; if no reviewer model is configured, it sends nothing and returns setup guidance. Otherwise it forwards the whole conversation. Give its advice serious weight, but adapt when a suggestion fails empirically or contradicts primary-source evidence.",
     ],
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, signal, onUpdate, ctx) {
@@ -871,8 +899,9 @@ export default function advisorExtension(pi: ExtensionAPI) {
     }
   });
 
-  // "On done": when the agent finishes, review and (if enabled) steer one follow-up.
-  pi.on("agent_end", async (_event, ctx) => {
+  // "On done": after retries, compaction recovery, and queued continuations have
+  // fully settled, review and (if enabled) steer one follow-up.
+  pi.on("agent_settled", async (_event, ctx) => {
     const projectTrusted = contextProjectTrusted(ctx);
     const { onDone } = effectiveTriggers(ctx.cwd, projectTrusted);
     if (!onDone || autoReviewedThisRound || autoRunning || isDisabled(ctx.cwd, projectTrusted) || isUnconfigured(ctx.cwd, projectTrusted)) return;
@@ -996,11 +1025,13 @@ export default function advisorExtension(pi: ExtensionAPI) {
       }
 
       const pickScope = async (): Promise<string | undefined> => {
-        const PROJECT_OPT = "This folder (project)";
-        const GLOBAL_OPT = "Global (all projects)";
-        const scope = await ctx.ui.select("Apply to", [PROJECT_OPT, GLOBAL_OPT]);
+        const projectTrusted = contextProjectTrusted(ctx);
+        if (!projectTrusted) {
+          ctx.ui.notify("Project advisor settings cannot be changed until this project is trusted; only global scope is available.", "warning");
+        }
+        const scope = await ctx.ui.select("Apply to", getAdvisorScopeChoices(projectTrusted));
         if (scope === undefined) return undefined;
-        return scope === PROJECT_OPT ? projectConfigPath(cwd) : globalConfigPath();
+        return scope === PROJECT_SCOPE ? projectConfigPath(cwd) : globalConfigPath();
       };
       const persist = (file: string, patch: AdvisorConfig) => {
         writeConfig(file, { ...readConfig(file), ...patch });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hk_net/pi-advisor",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Pi advisor extension: consult a configured reviewer model on the full conversation transcript",
   "type": "module",
   "private": false,
@@ -11,7 +11,10 @@
     "advisor"
   ],
   "license": "EUPL-1.2",
-  "author": "hknet",
+  "author": {
+    "name": "KAPPER NETWORK-COMMUNICATIONS GmbH",
+    "url": "https://kapper.net"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/hknet/pi-extensions.git",
@@ -26,10 +29,24 @@
     "README.md",
     "CHANGELOG.md"
   ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.84.1",
-    "@earendil-works/pi-coding-agent": ">=0.84.1",
-    "@earendil-works/pi-tui": ">=0.84.1"
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
   },
   "pi": {
     "extensions": [