@ian-pascoe/pi-advisor 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Ian Pascoe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# Pi Advisor
+
+`@ian-pascoe/pi-advisor` reviews a Pi agent's completed work and surfaces concise, attributed corrective advice when it finds material instruction violations, scope drift, repeated failures, or unsupported completion claims.
+
+Requires Pi `0.85.1` and Node `>=22.19.0`. Other Pi versions pause review with an explicit compatibility error.
+
+## Install
+
+```bash
+pi install npm:@ian-pascoe/pi-advisor
+# or from this checkout
+pi -e ./packages/pi-advisor/src/index.ts
+```
+
+Advisor is **disabled by default**. Configuration precedence is session, trusted project, global, then package defaults. Settings use Pi's native settings files and session entries; no separate database or transcript store is created.
+
+## Commands
+
+```text
+/advisor status
+/advisor on|off [--global|--project]
+/advisor inherit [key] [--global|--project]
+/advisor set <key> <JSON> [--global|--project]
+/advisor prompt [--global|--project]
+/advisor set includeSubagents true
+/advisor set model "provider/model-id"
+```
+
+Argument autocomplete suggests command names, settings keys, and valid trailing scope flags.
+
+`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).
+
+## Defaults and access
+
+| Option                         | Default                      |
+| ------------------------------ | ---------------------------- |
+| Enabled                        | `false`                      |
+| Watched sessions               | Main only                    |
+| Allowed tools                  | `read`, `grep`, `find`, `ls` |
+| Catch-up threshold             | `3`                          |
+| Review deadline                | 120 seconds                  |
+| Investigative calls per Review | 8                            |
+| 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. CodeMode-only tools require an explicitly compatible transport grant; Advisor never adds aliases, autogrants missing tools, or changes CodeMode exposure.
+
+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 0.85.1's hidden inline `llama.cpp` built-in is recreated from the installed Pi package's shipped extension file, retaining its ordered metadata and fresh provider state. This is a fixed-version compatibility recipe, not general inline-factory support; it requires the shipped file and the built-in's expected registration shape. 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.
+
+## Scheduling and safety
+
+Reviews combine completed observed turns (one model response plus its tool batches) and use bounded catch-up waits of at most 30 seconds. Each Review has its own deadline and tool-call budget. Findings are deduplicated without merging distinct code identifiers; ordinary concerns observe a three-turn cooldown, while blockers bypass cooldown but not duplicate or per-Review limits.
+
+Running work receives native steering. A blocker after normal interactive completion may receive a tracked corrective continuation within the configured budget; aborted, uncertain, deliberately interrupted, and headless-completed work is preserved without a hidden restart. Child corrections stay inside Minimal's owned operation. Headless root shutdown allows only a bounded final drain and never starts hidden corrective work.
+
+Status reports effective settings, sources, review state, backlog, usage/cost, and the last error. Unknown cost is shown as unknown, never zero. Review failure pauses Advisor while leaving the observed agent running; changing configuration, branch, or session identity invalidates stale in-flight work.
+
+Advisor is privileged extension code. Review inherited extensions and granted tools before installing it in a session with access to local files, credentials, or mutating APIs.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@ian-pascoe/pi-advisor",
+  "version": "0.0.0",
+  "private": false,
+  "description": "Background review and attributed corrective advice for Pi agent sessions.",
+  "keywords": [
+    "advisor",
+    "pi",
+    "pi-extension",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/ian-pascoe/pi-extensions/tree/main/packages/pi-advisor",
+  "bugs": {
+    "url": "https://github.com/ian-pascoe/pi-extensions/issues"
+  },
+  "license": "MIT",
+  "author": "Ian Pascoe <ian.g.pascoe@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ian-pascoe/pi-extensions.git",
+    "directory": "packages/pi-advisor"
+  },
+  "files": [
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "vitest run --config ../../vitest.config.ts --root .",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@ian-pascoe/pi-utils": "^0.2.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "0.85.1",
+    "@earendil-works/pi-ai": "0.85.1",
+    "@earendil-works/pi-coding-agent": "0.85.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/skills/pi-advisor/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: pi-advisor
+description: Diagnose Pi Advisor when reviews are missing, the Advisor is paused, settings are ineffective, backlog waits do not release, or corrective advice is not delivered safely.
+license: MIT
+---
+
+# Pi Advisor
+
+Use this sequence for a live Advisor problem:
+
+1. Run `/advisor status`. Record the effective settings, each setting's source, review state, backlog, usage/cost, and last error. Treat unknown cost as unknown, not zero.
+2. If the state is disabled, check the selected session override, trusted-project settings, and global settings in that order. Advisor defaults to disabled. Use `/advisor on`, `/advisor off`, `/advisor inherit`, or `/advisor set <key> <JSON>` at the intended scope; use `/advisor prompt` for the native prompt editor. Confirm the selected branch after resume, fork, or tree navigation.
+3. If the state is paused, read the reported capability or review error. Correct the setting or unavailable runtime capability, then explicitly re-enable or reload as the diagnostic instructs. A pause leaves the observed agent running.
+4. For missing reviews, inspect backlog and catch-up configuration. Backlog counts completed model responses with their tool batches, including work under review. `off` never waits; a positive threshold waits only while backlog is at least that threshold, and each wait is capped at 30 seconds. A review has its own deadline and investigative-call limit.
+5. If Context Management is loaded, verify that all three private tools—`context_notes`, `context_history`, and `context_rollover`—are explicitly granted. Any missing grant pauses Advisor before review. These tools operate on the Advisor Session's private Notes, History, and Checkpoints; they never grant access to the observed session. Confirm native settlement and checkpoint completion rather than treating an early response or `agent_end` report as completion.
+6. For tool or CodeMode failures, compare the effective `allowedTools` list with the loaded registry. Missing names are reported and ignored. CodeMode-only exposure needs an explicitly compatible transport grant; Advisor does not add aliases, autogrant tools, or change exposure mode. A Tool Grant covers the tool's full native interface and is not a filesystem or operation sandbox.
+7. For stale, duplicated, or unsafe advice, check branch/session identity and configuration-generation changes. Advisor Sessions are separate persisted native sessions with fresh extension resources. Unsupported opaque inline/custom resources pause rather than being reused. Running work is steered through Pi's native boundary; blockers after normal interactive completion use only tracked, budgeted Corrective Turns. Deliberately interrupted, aborted, uncertain, and headless-completed work is preserved without restart. Child correction must finish inside Minimal's owned operation.
+8. On shutdown, allow only the bounded headless final drain. Verify that no hidden corrective turn starts after root completion and that native Advisor resources are aborted before disposal.
+
+Finish when `/advisor status` shows the intended settings and a Review has settled without error: either an attributed finding is visible or Advisor remains silent with zero backlog. If a capability remains unsupported, report the exact diagnostic instead of bypassing native lifecycle or permission policy.

package/src/advisor-command.ts

@@ -0,0 +1,58 @@
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import {
+  advisorOptionKey,
+  advisorOptionKeys,
+  parseAdvisorOptions,
+  type AdvisorOptions,
+} from "./advisor-settings.js";
+
+/** Native command completion values replace the entire argument prefix. */
+export function completeAdvisorCommandArguments(prefix: string): AutocompleteItem[] {
+  const candidates = ["on", "off", "status", "prompt", "inherit", "set"];
+  const keyPrefix = /^((?:set|inherit)\s+)\S*$/.exec(prefix)?.[1];
+  if (keyPrefix) candidates.push(...advisorOptionKeys.map((key) => `${keyPrefix}${key}`));
+  const scopePrefix = /^(.*\s+)(--\S*)?$/s.exec(prefix)?.[1];
+  if (scopePrefix) {
+    try {
+      const command = parseAdvisorCommand(scopePrefix);
+      if (command.action !== "status" && command.scope === "session")
+        candidates.push(`${scopePrefix}--global`, `${scopePrefix}--project`);
+    } catch {
+      // Incomplete commands and JSON values cannot accept a scope yet.
+    }
+  }
+  return candidates
+    .filter((value) => value.startsWith(prefix))
+    .map((value) => ({ value, label: value }));
+}
+
+const usage =
+  "Usage: /advisor [on|off|status|prompt|inherit [key]|set <key> <JSON>] [--global|--project]";
+
+/** Parse one configuration change; validated patches cannot invent option keys. */
+export function parseAdvisorCommand(input: string) {
+  const flag = /\s+--(global|project)$/.exec(input.trim());
+  const scope =
+    flag?.[1] === "global"
+      ? ("global" as const)
+      : flag?.[1] === "project"
+        ? ("project" as const)
+        : ("session" as const);
+  const text = (flag ? input.trim().slice(0, flag.index) : input.trim()) || "status";
+  if (text === "status") {
+    if (flag) throw new Error(usage);
+    return { 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" } };
+  }
+  const inherit = /^inherit(?:\s+(\S+))?$/.exec(text);
+  if (inherit) {
+    return { action: "inherit" as const, scope, key: advisorOptionKey(inherit[1] ?? "enabled") };
+  }
+  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 };
+}