specpi 0.26.0 → 0.28.0

package/extensions/workflow-controls/index.ts

@@ -884,7 +884,7 @@ export default function workflowControls(pi: ExtensionAPI) {
     pi.registerTool({
         name: "request_capability",
         label: "Request Capability",
-        description: `Ask the user to restore a withdrawn SpecPi tool group for this session. Available groups — ${describeCapabilities()}. Their tools are hidden to keep each request small, so request a group only when the current task actually needs it, and continue without it if the user declines. The restored tools are usable from your next message and stay available until the session ends. Delegation is not requestable here; ask the user to run /delegate on.`,
+        description: `Ask the user to restore a withdrawn SpecPi tool group for this session. Available groups — ${describeCapabilities()}. Their tools are hidden to keep each request small, and restoring one mid-session also discards the provider's cached prompt prefix, which measured about 20% of a mid-length attempt's cost in this project's own testing — so request a group only when the current task actually needs it, and continue without it if the user declines. The restored tools are usable from your next message and stay available until the session ends. Delegation is not requestable here; ask the user to run /delegate on.`,
         parameters: Type.Object(
             {
                 capability: StringEnum(CAPABILITY_NAMES, {
@@ -959,7 +959,7 @@ export default function workflowControls(pi: ExtensionAPI) {
                 standing ||
                 (await ctx.ui.confirm(
                     `Allow ${capability.label} for this session?`,
-                    `The agent asked to ${capability.summary}. Reason given: ${safeMessage(params.reason)}\n\nThis offers ${pending.length} tool${pending.length === 1 ? "" : "s"} for the rest of this session and adds ${capability.schemaCost}. Withdraw them again with ${capability.command} off.`,
+                    `The agent asked to ${capability.summary}. Reason given: ${safeMessage(params.reason)}\n\nThis offers ${pending.length} tool${pending.length === 1 ? "" : "s"} for the rest of this session, adds ${capability.schemaCost}, ${capability.activationCost}. Withdraw them again with ${capability.command} off.`,
                 ));
             if (!accepted) {
                 return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specpi",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Scope control and a human-selected harness improvement loop for Pi",
   "author": "Tanner Middleton",
   "repository": {

package/scripts/packages.mjs

@@ -48,6 +48,54 @@ export function runBrowserQA(agentDir, command) {
     }
 }
 
+/**
+ * Packages a past SpecPi version pinned and this one no longer does.
+ *
+ * Dropping an entry from `templates/settings.json` stops new installs getting it and does nothing at
+ * all to a machine that already has it: the entry stays in `settings.json` and Pi keeps loading it.
+ * That is tolerable for a package that merely stopped being useful, and not tolerable for
+ * `specpi-jev-guard`, which fails closed -- an install left holding it after SpecPi deleted both the
+ * code that kept it inert and the `/jev guard off` command that could disarm it would block every
+ * shell call the moment its key or its endpoint went away, with nothing left to turn it off.
+ *
+ * So retirement is explicit, and it removes the entry rather than waiting for the restore path to.
+ */
+export const retiredPackages = Object.freeze(["npm:specpi-jev-guard"]);
+
+/**
+ * Drop retired entries from a settings object, in place, returning what was removed.
+ *
+ * Every entry goes, whatever shape it has. That is a deliberate exception to the ownership rule the
+ * restore path applies elsewhere -- "a user-modified entry is theirs" -- and the exception is the
+ * reason the list is not open to additions. Preserving a modified `specpi-jev-guard` entry preserved
+ * a fail-closed gate that this release removed the controls for: the code that rewrote its global
+ * configuration to `enabled: false` at every session start is gone, and so is `/jev guard off`, so a
+ * preserved entry is a gate that refuses every shell call the moment its key or endpoint goes away,
+ * with nothing left to turn it off. Filters are worth less than that.
+ *
+ * The removed entry is returned verbatim so the caller can print it back, and the write it belongs
+ * to is inside the installer's transaction and backed up with everything else. Version is not
+ * consulted: the reason for retirement is the package.
+ */
+export function removeRetiredPackages(settings) {
+    if (!Array.isArray(settings?.packages)) {
+        return [];
+    }
+
+    const removed = [];
+    settings.packages = settings.packages.filter((entry) => {
+        if (!retiredPackages.includes(packageIdentity(entry))) {
+            return true;
+        }
+
+        removed.push(packageSource(entry));
+
+        return false;
+    });
+
+    return removed;
+}
+
 export function packageChanges(before, after) {
     return basePackages.map((source) => {
         const identity = packageIdentity(source);
@@ -134,6 +182,14 @@ export function installBasePackages(agentDir) {
 
 export function checkBasePackages(agentDir, settings) {
     const errors = [];
+    for (const entry of Array.isArray(settings.packages) ? settings.packages : []) {
+        if (retiredPackages.includes(packageIdentity(entry))) {
+            errors.push(
+                `Retired base package still configured: ${packageSource(entry)}. Run specpi update to unpin it.`,
+            );
+        }
+    }
+
     for (const source of basePackages) {
         const identity = packageIdentity(source);
         const entry =

package/scripts/specpi.mjs

@@ -22,7 +22,14 @@ import {
 import { validateCapabilityRegistry } from "../extensions/tool-wishlist/registry.mjs";
 import { runValidator } from "../extensions/tool-wishlist/validators.mjs";
 import { acquireSpecPiLock } from "./lock.mjs";
-import { basePackages, checkBasePackages, installBasePackages, packageChanges, runBrowserQA } from "./packages.mjs";
+import {
+    basePackages,
+    checkBasePackages,
+    installBasePackages,
+    packageChanges,
+    removeRetiredPackages,
+    runBrowserQA,
+} from "./packages.mjs";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const VERSION = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8")).version;
@@ -46,6 +53,27 @@ const resourcePaths = [
     "extensions/tool-wishlist/registry.mjs",
     "extensions/tool-wishlist/validators.mjs",
     "extensions/tool-wishlist/capabilities.json",
+    "extensions/tool-wishlist/authoring-tools.mjs",
+    "extensions/jev-advisor/index.ts",
+    "extensions/jev-advisor/config.mjs",
+    "extensions/jev-advisor/consent.mjs",
+    "extensions/jev-advisor/ledger.mjs",
+    "extensions/jev-advisor/sanitize.mjs",
+    "extensions/jev-advisor/usage.mjs",
+    "extensions/jev-advisor/client.mjs",
+    "extensions/jev-advisor/key-source.mjs",
+    "extensions/jev-advisor/layer.mjs",
+    "extensions/jev-advisor/risk.mjs",
+    "extensions/jev-advisor/questions/guard.mjs",
+    "extensions/jev-advisor/broker.mjs",
+    "extensions/jev-advisor/gate.mjs",
+    "extensions/jev-advisor/questions/retention.mjs",
+    "extensions/jev-advisor/questions/compaction.mjs",
+    "extensions/jev-advisor/questions/gap.mjs",
+    "extensions/jev-advisor/questions/sources.mjs",
+    "extensions/jev-advisor/questions/progress.mjs",
+    "extensions/jev-advisor/questions/untrusted.mjs",
+    "extensions/jev-advisor/questions/capabilities.mjs",
     "skills/specpi-improve/SKILL.md",
 ];
 
@@ -59,7 +87,7 @@ Usage:
   specpi doctor
   specpi uninstall [--yes]
 
-Installs /scope, the harness improvement loop, and six pinned packages.
+Installs /scope, the harness improvement loop, and seven pinned packages.
 The base is tested with Pi 0.84.4. Run specpi plan to see package versions.
 --skip-package-install installs only the core, or preserves an existing base on update.
 --skip-browser-install skips Chromium setup, not package acquisition or doctor checks.
@@ -142,7 +170,9 @@ function validateManifestPaths(manifest) {
         assertLocalPath(target, agentDir);
         const relative = path.relative(agentDir, target).replaceAll("\\", "/");
         if (
-            !/^(extensions\/(?:workflow-controls|tool-wishlist|browser|command-guard|delegation|background-tasks|structural-search|files|spec|specpi-ui-refresh)\/[^/]+|extensions\/spec\.ts|skills\/(?:specpi-improve|donsetch)\/SKILL\.md|themes\/(?:tea-house|specpi-spec)\.json|specpi\/pi-profiles\.sh)$/.test(
+            // jev-advisor is the one managed extension with a subdirectory, so it is listed
+            // separately rather than loosening the single-segment rule for every other family.
+            !/^(extensions\/(?:workflow-controls|tool-wishlist|browser|command-guard|delegation|background-tasks|structural-search|files|spec|specpi-ui-refresh)\/[^/]+|extensions\/jev-advisor\/(?:questions\/)?[^/]+|extensions\/spec\.ts|skills\/(?:specpi-improve|donsetch)\/SKILL\.md|themes\/(?:tea-house|specpi-spec)\.json|specpi\/pi-profiles\.sh)$/.test(
                 relative,
             )
         ) {
@@ -230,6 +260,32 @@ function restoreLegacySettings(manifest, warnings) {
     writeJson(settingsPath, settings, existingMode(settingsPath, 0o600));
 }
 
+/**
+ * Unpin a package a past version installed and this one has retired.
+ *
+ * Deliberately outside the `--skip-packages` guard. Skipping package acquisition means not
+ * downloading or re-pinning anything, and it has never meant leaving an entry SpecPi itself wrote
+ * pointing at code SpecPi has since removed the controls for -- `specpi-jev-guard` is fail-closed,
+ * so the machine that skipped packages is exactly the machine that would keep it armed forever.
+ *
+ * `settingsPath` is in the transaction's watched set for every non-uninstall operation, so this
+ * write is snapshotted, backed up and rolled back with everything else.
+ */
+function retireBasePackages(warnings) {
+    const settings = readJson(settingsPath, {});
+    const removed = removeRetiredPackages(settings);
+    if (removed.length === 0) {
+        return;
+    }
+
+    writeJson(settingsPath, settings, existingMode(settingsPath, 0o600));
+    for (const source of removed) {
+        warnings.push(
+            `Unpinned retired package: ${source}. Its downloaded files stay in the agent npm directory, Pi no longer loads it, and any settings of your own on that entry are in this run's backup.`,
+        );
+    }
+}
+
 function removeLegacyShell(manifest) {
     if (manifest?.shellRc && fs.existsSync(manifest.shellRc)) {
         const result = removeManagedBlock(fs.readFileSync(manifest.shellRc, "utf8"), SHELL_START, SHELL_END);
@@ -284,7 +340,16 @@ async function mutate(options, operation) {
             ...files.map(([, target]) => target),
             ...Object.keys(previous?.files || {}),
         ];
-        if (!options.skipPackages || previous?.settingsChanges?.length || previous?.packageChanges?.length) {
+        // Watched whenever anything in this run can write it. `retireBasePackages` runs on every
+        // non-uninstall operation, including under `--skip-package-install`, so the narrower
+        // condition that used to guard this left that write outside the snapshot -- unbacked up, and
+        // not rolled back by a later failure in the same transaction.
+        if (
+            operation !== "uninstall" ||
+            !options.skipPackages ||
+            previous?.settingsChanges?.length ||
+            previous?.packageChanges?.length
+        ) {
             watched.push(settingsPath);
         }
 
@@ -305,6 +370,10 @@ async function mutate(options, operation) {
         const warnings = [];
         const preserveBase = operation !== "uninstall" && options.skipPackages && previous?.basePackages?.length;
         restoreLegacySettings(preserveBase ? { ...previous, packageChanges: [] } : previous, warnings);
+        if (operation !== "uninstall") {
+            retireBasePackages(warnings);
+        }
+
         removeLegacyShell(previous);
         let packageState = preserveBase
             ? {