@ian-pascoe/pi-advisor 0.3.5 → 0.4.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
 
@@ -41,6 +41,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 +56,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.4.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-observer.ts

@@ -466,6 +466,12 @@ export class AdvisorObserver {
         label: "Advisor report",
         description: `Finish the Review with up to ${this.config.maxFindingsPerReview} concise, actionable findings. Prioritize blockers, then concerns, then worthwhile nits.`,
         parameters: reportSchema,
+        annotations: {
+          readOnlyHint: false,
+          destructiveHint: false,
+          idempotentHint: false,
+          openWorldHint: false,
+        },
         prepareArguments: (arguments_) => {
           if (Value.Check(reportSchema, arguments_)) return arguments_;
           if (!Value.Check(legacyReportSchema, arguments_))

package/src/advisor-session.ts

@@ -19,7 +19,6 @@ import type {
   ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import type { AdvisorConfig } from "./advisor-settings.js";
-import { advisorRuntimeWarning, isCallable } from "./advisor-runtime.js";
 
 /** Explicit file-selection recipe supplied by the resource owner, never inferred from opaque loaders. */
 export interface AdvisorResourceInputs {
@@ -149,8 +148,6 @@ export async function createAdvisorSession(
   observed: AgentSession,
   options: AdvisorSessionOptions,
 ): Promise<AgentSessionRuntime> {
-  const unsupported = advisorRuntimeWarning();
-  if (unsupported) throw new Error(unsupported);
   options.signal?.throwIfAborted();
   const cancelled = Promise.withResolvers<never>();
   const abort = () =>
@@ -225,10 +222,6 @@ async function buildAdvisorSession(
     const factoryExport = builtinFactories.get(name);
     if (builtin && factoryExport) {
       const create = piSdk[factoryExport];
-      if (!isCallable(create))
-        throw new Error(
-          `Unsupported Advisor resources: this Pi runtime does not export ${factoryExport} to recreate ${extension.path}`,
-        );
       recreated.add(index);
       const codemodeModels = options.resourceInputs?.codemodeModels;
       builtins.push({
@@ -244,10 +237,6 @@ async function buildAdvisorSession(
     }
     // Pi ships a fresh file-backed llama.cpp factory but does not export it.
     if (builtin && name === "llama.cpp") {
-      if (!isCallable(piSdk.getPackageDir))
-        throw new Error(
-          "Unsupported Advisor resources: this Pi runtime does not export getPackageDir to locate llama.cpp",
-        );
       const path = join(piSdk.getPackageDir(), "dist", "extensions", "llama", "index.js");
       if (!existsSync(path))
         throw new Error(
@@ -458,6 +447,18 @@ async function buildAdvisorSession(
     };
     if (sessionStartEvent) sessionOptions.sessionStartEvent = sessionStartEvent;
     const created = await piSdk.createAgentSessionFromServices(sessionOptions);
+    // Pi's `tools` option is the ceiling and also activates (declares) every named tool. Keep
+    // `codemode` and `deferred` grants callable but undeclared, as Pi's own defaults do;
+    // later registrations follow the same rule, and extensions can still declare them.
+    const scriptOnly = new Set(
+      created.session
+        .getAllTools()
+        .filter(({ exposure }) => exposure === "codemode" || exposure === "deferred")
+        .map(({ name }) => name),
+    );
+    created.session.setActiveToolsByName(
+      created.session.getActiveToolNames().filter((name) => !scriptOnly.has(name)),
+    );
     return { ...created, services, diagnostics: services.diagnostics };
   };
   const runtime = await piSdk.createAgentSessionRuntime(factory, {

package/src/index.ts

@@ -18,7 +18,6 @@ import {
 import { completeAdvisorCommandArguments, parseAdvisorCommand } from "./advisor-command.js";
 import { AdvisorObserver } from "./advisor-observer.js";
 import { isAdvisorSession, type AdvisorResourceInputs } from "./advisor-session.js";
-import { advisorRuntimeWarning } from "./advisor-runtime.js";
 import { TROUBLESHOOTING_HINT } from "./troubleshooting-skill.js";
 
 interface WatchedChild {
@@ -46,8 +45,6 @@ const childRequestSchema = Type.Object({
 
 /** Review an observed session without changing its tools or standing instructions. */
 export default function advisor(pi: ExtensionAPI): void {
-  // Capability checks, not version pins: an unmet requirement warns and leaves the Advisor unavailable.
-  const unsupported = advisorRuntimeWarning();
   let warn: (message: string) => void = () => {};
   let observed: AgentSession | undefined;
   let error: string | undefined;
@@ -76,6 +73,12 @@ export default function advisor(pi: ExtensionAPI): void {
         description:
           "Ask the enabled Advisor for analysis or a second opinion. Waits for its answer; does not delegate implementation.",
         parameters: askToolParameters,
+        annotations: {
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+          openWorldHint: false,
+        },
         executionMode: "sequential",
         execute: async (_id, { message }, signal) => {
           try {
@@ -147,12 +150,6 @@ export default function advisor(pi: ExtensionAPI): void {
         // A replaced session's UI is stale; the native status entry remains the durable record.
       }
     };
-    if (unsupported) {
-      error = unsupported;
-      setAskToolAvailable(false);
-      warn(unsupported);
-      return;
-    }
     const found = discoverPiAgentSession(pi, piSdk.AgentSession);
     if (found.ok) {
       observed = found.session;
@@ -215,7 +212,6 @@ export default function advisor(pi: ExtensionAPI): void {
   // oxlint-disable-next-line anti-slop/no-unknown-parameters -- SAFETY: The native owner bus is a boundary; validate identity, SDK instance, and exact resource metadata before attachment.
   function attachChild(payload: unknown): void {
     if (
-      unsupported ||
       !Value.Check(childRequestSchema, payload) ||
       !(payload.session instanceof piSdk.AgentSession)
     )

package/src/advisor-runtime.ts

@@ -1,97 +0,0 @@
-import * as piAi from "@earendil-works/pi-ai";
-import * as piSdk from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { Value } from "typebox/value";
-
-const callable = Type.Function([], Type.Unknown());
-
-/** True when a native SDK member is present and callable. */
-export function isCallable<T>(value: T): boolean {
-  return Value.Check(callable, value);
-}
-
-/** True when `owner` exposes `name` as a callable, including module getters and inherited methods. */
-function hasMember<T extends object>(owner: T | undefined, name: string): boolean {
-  if (!owner) return false;
-  if (Value.Check(Type.Object({ [name]: callable }), owner)) return true;
-  // TypeBox does not treat classes as objects, so read class statics as own data properties.
-  return isCallable(Object.getOwnPropertyDescriptor(owner, name)?.value);
-}
-
-function missingMembers<T extends object>(
-  label: string,
-  owner: T | undefined,
-  names: readonly string[],
-): string[] {
-  return names.filter((name) => !hasMember(owner, name)).map((name) => `${label}${name}`);
-}
-
-/**
- * Pi capabilities the Advisor needs to observe a session and recreate a private native one.
- * Modules are read through namespaces so a missing export is reported here instead of failing
- * extension load. Built-in extension factories are checked only when the observed session uses them.
- */
-export function advisorRuntimeIssues(
-  ai: Partial<typeof piAi> = piAi,
-  sdk: Partial<typeof piSdk> = piSdk,
-): string[] {
-  return [
-    ...missingMembers("pi-ai ", ai, [
-      "InMemoryCredentialStore",
-      "contentText",
-      "getCurrentSystemPrompt",
-      "getCurrentTools",
-      "toToolDeclaration",
-    ]),
-    ...missingMembers("", sdk, [
-      "AgentSession",
-      "AgentSessionRuntime",
-      "DefaultResourceLoader",
-      "ModelRuntime",
-      "SessionManager",
-      "SettingsManager",
-      "convertToLlm",
-      "createAgentSessionFromServices",
-      "createAgentSessionRuntime",
-      "createAgentSessionServices",
-      "defineTool",
-    ]),
-    ...missingMembers("SessionManager.", sdk.SessionManager, ["create"]),
-    ...missingMembers("SettingsManager.", sdk.SettingsManager, ["fromStorage"]),
-    ...missingMembers("SettingsManager#", sdk.SettingsManager?.prototype, [
-      "applyOverrides",
-      "getGlobalSettings",
-      "getProjectSettings",
-      "isProjectTrusted",
-    ]),
-    ...missingMembers("ModelRuntime.", sdk.ModelRuntime, ["create"]),
-    ...missingMembers("ModelRuntime#", sdk.ModelRuntime?.prototype, [
-      "getAuth",
-      "getModel",
-      "getRegisteredProviderIds",
-      "isUsingOAuth",
-      "listCredentials",
-      "setRuntimeApiKey",
-    ]),
-    ...missingMembers("AgentSession#", sdk.AgentSession?.prototype, [
-      "abort",
-      "bindExtensions",
-      "getActiveToolNames",
-      "getAllTools",
-      "getSessionStats",
-      "prompt",
-      "sendCustomMessage",
-      "subscribe",
-    ]),
-    ...missingMembers("AgentSessionRuntime#", sdk.AgentSessionRuntime?.prototype, [
-      "dispose",
-      "setRebindSession",
-    ]),
-  ];
-}
-
-/** User-facing explanation for unmet requirements, or undefined when the runtime is supported. */
-export function advisorRuntimeWarning(issues = advisorRuntimeIssues()): string | undefined {
-  if (!issues.length) return undefined;
-  return `Advisor is unavailable: this Pi runtime lacks ${issues.join(", ")}`;
-}