@ian-pascoe/pi-advisor 0.3.5 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 `@ian-pascoe/pi-advisor` reviews a Pi agent's completed work and surfaces concise, attributed findings for material problems and worthwhile low-risk cleanup.
 
-Requires Node `>=22.19.0`. Advisor does not pin a Pi version: at load it checks the Pi SDK exports and methods it uses. If any are missing, it warns, hides `advisor_ask`, and stays unavailable; `/advisor status` names the missing requirements. The observed session keeps working.
+Requires Node `>=22.19.0` and Pi `>=0.99.0`.
 
 ## Install
 
@@ -17,6 +17,7 @@ Advisor is **disabled by default**. Configuration precedence is session, trusted
 ## Commands
 
 ```text
+/advisor
 /advisor status
 /advisor on|off [--global|--project]
 /advisor inherit [key] [--global|--project]
@@ -29,6 +30,12 @@ Advisor is **disabled by default**. Configuration precedence is session, trusted
 
 Argument autocomplete suggests command names, settings keys, and valid trailing scope flags.
 
+In the interactive TUI, `/advisor` alone opens a settings menu built from Pi's native settings list, like `/settings`. A Scope row chooses where edits are written (session, trusted project, or global), and each setting shows its effective value with any non-default source. `enabled`, `includeSubagents`, and `thinkingLevel` cycle the selected scope's own value in place (`inherit → on → off`, or through each thinking level); while that scope has none, the row shows what it inherits, such as `inherit (on · project)`, and a value overridden by a higher-precedence scope is marked. Model, tools, numbers, and the prompt open submenus, and the prompt uses Pi's own editor component. Every edit is validated and applied immediately; a paused Advisor shows its reason and a Resume row. Closing the menu records one status entry listing the changes it applied, or nothing if none were. Without the TUI, `/advisor` records the status entry instead.
+
+`/advisor status` and the other subcommands each record a status entry in the transcript. Collapsed, it shows state, model, backlog, usage and cost, unavailable tools, and the last error; expanded, it lists every setting with its source and each watched Child Agent. A mutating command's entry starts with the changes it applied. While enabled, the footer shows `advisor` when idle, `advisor: reviewing`/`consulting` with any `backlog N`, or `advisor: paused`, plus Child Agents that are reviewing or paused. `advisor_ask` renders its question and a Markdown answer preview, and Child Agent findings carry a `↳ <agentId>` label.
+
+Interventions render with their severity and Advisor attribution. Long Nits collapse until expanded; Concerns and Blockers always show in full.
+
 ## On-demand consultations
 
 When Advisor is enabled, the main agent can call `advisor_ask({ message })` for analysis or a second opinion. The call waits for the current Review, then returns plain Markdown before any further Review Backlog is processed. Follow-up calls continue the same private Advisor Session.
@@ -41,6 +48,8 @@ Consultation authorizes analysis and investigation, not implementation or other
 
 `prompt` opens Pi's native editor and replaces the whole Advisor Prompt. `inherit` removes an override at the selected scope. Invalid keys and values are rejected. Lists, including `allowedTools`, replace the inherited list rather than merge. `catchUpThreshold` accepts any positive safe integer or `"off"`; `reviewTimeoutMs` accepts 1–2,147,483,647 milliseconds (the native timer range); `maxFindingsPerReview` accepts an integer from 1 through 32.
 
+`advisor_ask` declares MCP-style `annotations` (read-only, non-destructive, idempotent, closed-world) that Pi reports through `pi.getAllTools()` for permission extensions; Pi does not send them to model providers. They describe the consultation itself, not the tools granted to the Advisor. The Advisor Session's internal `advisor_report` tool, which extensions inherited by that session can see, declares non-destructive, closed-world annotations and is not read-only, because it records the Review's findings.
+
 ## Defaults and access
 
 | Option                         | Default                      |
@@ -54,13 +63,13 @@ Consultation authorizes analysis and investigation, not implementation or other
 | Findings per Review            | 4                            |
 | Automatic Corrective Turns     | 1 per request/task           |
 
-A Tool Grant names tools; it does not sandbox their full native interfaces. Explicitly granting `lsp`, for example, permits its native operations, including mutations. Unavailable names are ignored and reported. Advisor never autogrants missing tools. Granting `codemode` lets the Advisor script its other granted tools; it inherits the observed `codemode.mode`, so under `"only"` the Advisor calls `advisor_report` from a script. It also inherits whether scripts get the `models` API: Minimal Subagents Child Agents have none, so neither do their Advisors.
+A Tool Grant names tools; it does not sandbox their full native interfaces. Explicitly granting `bash`, for example, permits any command, including mutations. Unavailable names are ignored and reported; status reflects the Advisor Session at that moment, so a granted tool that registers later, such as an MCP tool after its server connects, is reported until it does. Advisor never autogrants missing tools. Granted tools with `codemode` or `deferred` exposure (such as tools from Pi's built-in MCP) are not declared to the Advisor model; they stay callable from granted `codemode` scripts, and a granted `tool_search` can declare them, as in the observed agent. Granting `codemode` lets the Advisor script its other granted tools; it inherits the observed `codemode.mode`, so under `"only"` the Advisor calls `advisor_report` from a script. It also inherits whether scripts get the `models` API: Minimal Subagents Child Agents have none, so neither do their Advisors.
 
 The Advisor inherits each observed agent's model and thinking level independently unless configured otherwise. One root policy can cover current and future Minimal Subagents descendants when enabled.
 
 ## Sessions and Context Management
 
-Each watched agent has a private, persisted native Advisor Session with fresh, session-bound extension resources. Reviews reuse that session until context or configuration changes require rebuilding. Pi's enabled `builtin:<name>` extensions are recreated in their observed order: `codemode`, `tool-search`, and `mcp` from Pi's exported factories, and `llama.cpp` from the installed Pi package's shipped extension file, retaining their metadata and fresh provider state. Built-ins disabled with `-builtin:<name>` stay absent. If Pi no longer exports a needed factory, the Advisor pauses with that diagnostic. This is a built-in recreation recipe, not general inline-factory support; a host factory registered under a built-in name is rejected. Other opaque inline or custom extension resources that cannot be safely recreated are reported as unsupported and pause the Advisor; they are not silently reused or omitted. The Advisor's session state remains separate from the observed agent's state.
+Each watched agent has a private, persisted native Advisor Session with fresh, session-bound extension resources. Reviews reuse that session until context or configuration changes require rebuilding. Pi's enabled `builtin:<name>` extensions are recreated in their observed order: `codemode`, `tool-search`, and `mcp` from Pi's exported factories, and `llama.cpp` from the installed Pi package's shipped extension file, retaining their metadata and fresh provider state. Built-ins disabled with `-builtin:<name>` stay absent. This is a built-in recreation recipe, not general inline-factory support; a host factory registered under a built-in name is rejected. Other opaque inline or custom extension resources that cannot be safely recreated are reported as unsupported and pause the Advisor; they are not silently reused or omitted. The Advisor's session state remains separate from the observed agent's state.
 
 Context Management is optional. If loaded and its tools are granted, `context_notes`, `context_history`, and `context_rollover` operate on the Advisor's private context. If any of those three tools is excluded, the Advisor pauses before reviewing. There is no autogrant or hook bypass.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-advisor",
-  "version": "0.3.5",
+  "version": "0.5.0",
   "private": false,
   "description": "Background review and attributed corrective advice for Pi agent sessions.",
   "keywords": [
@@ -32,13 +32,13 @@
     "provenance": true
   },
   "dependencies": {
-    "@ian-pascoe/pi-utils": "^0.3.0"
+    "@ian-pascoe/pi-utils": "^0.3.1"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-agent-core": ">=0.99.0",
+    "@earendil-works/pi-ai": ">=0.99.0",
+    "@earendil-works/pi-coding-agent": ">=0.99.0",
+    "@earendil-works/pi-tui": ">=0.99.0",
     "typebox": "*"
   },
   "engines": {

package/src/advisor-command.ts

@@ -15,7 +15,7 @@ export function completeAdvisorCommandArguments(prefix: string): AutocompleteIte
   if (scopePrefix) {
     try {
       const command = parseAdvisorCommand(scopePrefix);
-      if (command.action !== "status" && command.scope === "session")
+      if ("scope" in command && command.scope === "session")
         candidates.push(`${scopePrefix}--global`, `${scopePrefix}--project`);
     } catch {
       // Incomplete commands and JSON values cannot accept a scope yet.
@@ -27,7 +27,7 @@ export function completeAdvisorCommandArguments(prefix: string): AutocompleteIte
 }
 
 const usage =
-  "Usage: /advisor [on|off|status|prompt|inherit [key]|set <key> <JSON>] [--global|--project]";
+  "Usage: /advisor [on|off|status|prompt|inherit [key]|set <key> <JSON>] [--global|--project]; /advisor alone opens settings";
 
 /** Parse one configuration change; validated patches cannot invent option keys. */
 export function parseAdvisorCommand(input: string) {
@@ -38,14 +38,19 @@ export function parseAdvisorCommand(input: string) {
       : flag?.[1] === "project"
         ? ("project" as const)
         : ("session" as const);
-  const text = (flag ? input.trim().slice(0, flag.index) : input.trim()) || "status";
-  if (text === "status") {
+  const text = flag ? input.trim().slice(0, flag.index) : input.trim();
+  if (text === "" || text === "status") {
     if (flag) throw new Error(usage);
-    return { action: "status" as const };
+    return text === "" ? { action: "menu" as const } : { action: "status" as const };
   }
   if (text === "prompt") return { action: "prompt" as const, scope };
   if (text === "on" || text === "off") {
-    return { action: "set" as const, scope, patch: { enabled: text === "on" } };
+    return {
+      action: "set" as const,
+      scope,
+      key: "enabled" as const,
+      patch: { enabled: text === "on" },
+    };
   }
   const inherit = /^inherit(?:\s+(\S+))?$/.exec(text);
   if (inherit) {
@@ -53,6 +58,7 @@ export function parseAdvisorCommand(input: string) {
   }
   const set = /^set\s+(\S+)\s+([\s\S]+)$/.exec(text);
   if (!set?.[1] || !set[2]) throw new Error(usage);
-  const patch: AdvisorOptions = parseAdvisorOptions({ [set[1]]: JSON.parse(set[2]) }, scope);
-  return { action: "set" as const, scope, patch };
+  const key = advisorOptionKey(set[1]);
+  const patch: AdvisorOptions = parseAdvisorOptions({ [key]: JSON.parse(set[2]) }, scope);
+  return { action: "set" as const, scope, key, patch };
 }

package/src/advisor-contract.ts

@@ -0,0 +1,33 @@
+import { Type, type Static } from "typebox";
+
+/** Intervention severities, in ascending urgency. */
+export const advisorSeveritySchema = Type.Union([
+  Type.Literal("nit"),
+  Type.Literal("concern"),
+  Type.Literal("blocker"),
+]);
+export type AdvisorSeverity = Static<typeof advisorSeveritySchema>;
+
+/** One reported finding; also the journaled details of an Intervention message. */
+export const advisorFindingSchema = Type.Object(
+  {
+    severity: advisorSeveritySchema,
+    message: Type.String({ minLength: 1, maxLength: 4000 }),
+  },
+  { additionalProperties: false },
+);
+export type AdvisorFinding = Static<typeof advisorFindingSchema>;
+
+/** Observer lifecycle state reported by its `status`. */
+export const advisorObserverStateSchema = Type.Union([
+  Type.Literal("disabled"),
+  Type.Literal("armed"),
+  Type.Literal("reviewing"),
+  Type.Literal("consulting"),
+  Type.Literal("paused"),
+]);
+export type AdvisorObserverState = Static<typeof advisorObserverStateSchema>;
+
+/** State recorded in status entries; private Advisor Sessions cannot host an Advisor. */
+export const advisorStateSchema = Type.Union([advisorObserverStateSchema, Type.Literal("private")]);
+export type AdvisorState = Static<typeof advisorStateSchema>;