specpi 0.26.0 → 0.27.0

package/extensions/tool-wishlist/authoring-tools.mjs

@@ -0,0 +1,42 @@
+// Phase 0 of the Jev advisor plan, which needs no model at all.
+//
+// Measured across the recorded eval runs, six of SpecPi's ten offered tools were offered on 31 of
+// 31 attempts and called zero times. Two of them are these: `record_harness_contract` and
+// `finish_harness_improvement` are *authoring* tools, usable only after a human has selected a
+// candidate through /harness-improvement. Whether a selection exists is a fact in local state, so
+// the answer is a boolean — no latency, no cost, no false positives, and nothing for a classifier
+// to route.
+//
+// `report_capability_gap` is deliberately not in this list. It is the *observation* tool and the
+// reason the improvement loop exists; withdrawing it would silently lose the friction reports the
+// loop is built to capture. It stays offered at all times.
+
+/** Only usable while an improvement is selected. */
+export const AUTHORING_TOOL_NAMES = Object.freeze(["record_harness_contract", "finish_harness_improvement"]);
+
+/**
+ * Add or remove the authoring tools without disturbing any other extension's tools. Mirrors the
+ * web-access gate: it only ever touches the names it owns, and it does nothing when the active set
+ * already matches, so a no-op never costs the cached prompt prefix.
+ */
+export function syncAuthoringTools(pi, selected) {
+    if (typeof pi?.getActiveTools !== "function" || typeof pi?.setActiveTools !== "function") {
+        return false;
+    }
+
+    const owned = new Set(AUTHORING_TOOL_NAMES);
+    const active = pi.getActiveTools();
+    const present = active.filter((name) => owned.has(name));
+    if (selected && present.length === owned.size) {
+        return false;
+    }
+
+    if (!selected && present.length === 0) {
+        return false;
+    }
+
+    const others = active.filter((name) => !owned.has(name));
+    pi.setActiveTools(selected ? [...others, ...AUTHORING_TOOL_NAMES] : others);
+
+    return true;
+}

package/extensions/tool-wishlist/index.ts

@@ -13,6 +13,7 @@ import { getMarkdownTheme, type ExtensionAPI } from "@earendil-works/pi-coding-a
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Box, Markdown, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import { syncAuthoringTools } from "./authoring-tools.mjs";
 import {
     appendWishlistDecision,
     archiveWishlist,
@@ -498,6 +499,9 @@ export default function toolWishlist(pi: ExtensionAPI) {
     let activeRunId = randomUUID();
     let activeImprovement: ActiveImprovement | undefined;
     let improvementLifecycleGeneration = 0;
+    // The authoring tools ride every request whether or not they can be used. Local state knows
+    // when they cannot be, so the answer is a boolean rather than a prediction.
+    const syncAuthoring = () => syncAuthoringTools(pi, activeImprovement !== undefined);
     let improvementMenuGeneration = 0;
     let finishBusy = false;
     let contractBusy = false;
@@ -583,15 +587,18 @@ export default function toolWishlist(pi: ExtensionAPI) {
 
     pi.on("session_start", (_event, ctx) => {
         restoreActiveImprovement(ctx);
+        syncAuthoring();
     });
 
     pi.on("session_tree", (_event, ctx) => {
         restoreActiveImprovement(ctx);
+        syncAuthoring();
     });
 
     pi.on("session_shutdown", () => {
         improvementLifecycleGeneration += 1;
         activeImprovement = undefined;
+        syncAuthoring();
     });
 
     const assertImprovementStillCurrent = (expected: ActiveImprovement, generation: number, ctx: any, signal?: any) => {
@@ -1131,6 +1138,7 @@ export default function toolWishlist(pi: ExtensionAPI) {
                 });
                 if (activeImprovement?.selectionId === selectedImprovement.selectionId) {
                     activeImprovement = undefined;
+                    syncAuthoring();
                 }
 
                 return {
@@ -1312,6 +1320,9 @@ export default function toolWishlist(pi: ExtensionAPI) {
                 ...policy,
             };
             assertSelectionContextCurrent();
+            // Pi offers tools added during a call from the next assistant message, so restoring
+            // them here lands exactly when the selection they belong to becomes usable.
+            syncAuthoring();
             pi.appendEntry(TASK_CONTRACT_ENTRY, { kind: "cleared" });
             leafId = ctx.sessionManager.getLeafId?.();
             assertSelectionContextCurrent();

package/extensions/workflow-controls/capabilities.mjs

@@ -37,11 +37,35 @@ export const BROWSER_TOOL_NAMES = Object.freeze([
  * the package's own state when it finishes, so a tool-name activation would undo itself.
  * Delegation needs an activation path inside its own package.
  */
+/**
+ * Restoring a group mid-session costs twice, and only one of those costs was ever stated.
+ *
+ * `schemaCost` is the standing price: those bytes ride every request until the group is withdrawn
+ * again. `activationCost` is the one-off, and it is much larger. Adding tool schemas partway
+ * through a session is not an additive change the provider can absorb -- it invalidates the cached
+ * prompt prefix, and the next request pays fresh input rates for the whole conversation so far.
+ *
+ * This was believed and reasoned about here for a long time and never measured. It is measured now.
+ * Three attempts on `t3-cascade-ledger` flipped the browser group on at turn 6: in all three,
+ * cached tokens collapsed to 3,200 at the next request while the prompt kept climbing, and the
+ * re-warm cost 14.6%, 21.6% and 23.9% of the attempt -- 20% on average, against a threshold of 10%
+ * fixed before the run. See `evals/runs/cache-probe/` and `scripts/cache-probe.mjs`.
+ *
+ * The same run says what to do about it: arming the same group from the first request cost 16% more
+ * than never arming it at all, against 47% for flipping mid-session. Paying up front is roughly
+ * three times cheaper than paying when the need appears.
+ */
 export const CAPABILITIES = Object.freeze({
     web: {
         label: "Web access",
         tools: WEB_TOOL_NAMES,
         schemaCost: "about 11 KB of tool schema per request",
+        // Not measured directly, and deliberately not extrapolated into a number. It is the larger
+        // schema, and pi-web-access is a third-party package that still carries promptSnippet and
+        // promptGuidelines, so activating it rebuilds the system prompt as well as the tool schema
+        // -- a second invalidation path Browser QA no longer has.
+        activationCost:
+            "and discards the cached prompt prefix once, which is not measured for this group but is at least as expensive as Browser QA's 20% of attempt cost, because its schema is larger and activating it also rebuilds the system prompt",
         summary: "search the web and fetch page or source content",
         command: "/webaccess",
     },
@@ -49,6 +73,8 @@ export const CAPABILITIES = Object.freeze({
         label: "Browser QA",
         tools: BROWSER_TOOL_NAMES,
         schemaCost: "about 8.7 KB of tool schema per request",
+        activationCost:
+            "and discards the cached prompt prefix once, measured at about 20% of a mid-length attempt's cost",
         summary: "open pages in an isolated browser to verify rendering, behavior and accessibility",
         command: "/browser",
     },

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.27.0",
   "description": "Scope control and a human-selected harness improvement loop for Pi",
   "author": "Tanner Middleton",
   "repository": {

package/scripts/specpi.mjs

@@ -23,6 +23,7 @@ import { validateCapabilityRegistry } from "../extensions/tool-wishlist/registry
 import { runValidator } from "../extensions/tool-wishlist/validators.mjs";
 import { acquireSpecPiLock } from "./lock.mjs";
 import { basePackages, checkBasePackages, installBasePackages, packageChanges, runBrowserQA } from "./packages.mjs";
+import { applyConfig as applyGuardConfig } from "../extensions/jev-advisor/guard.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 +47,24 @@ 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/broker.mjs",
+    "extensions/jev-advisor/gate.mjs",
+    "extensions/jev-advisor/guard.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",
 ];
 
@@ -142,7 +161,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,
             )
         ) {
@@ -333,6 +354,17 @@ async function mutate(options, operation) {
                 runBrowserQA(agentDir, "setup");
             }
 
+            // specpi-jev-guard's own default is enabled:true, so a freshly installed base would
+            // start gating shell and file calls through a third-party service before anyone asked
+            // for it — and with no key it fails closed, which means a first install that refuses to
+            // run commands. The advisor rewrites this at every session start, but that only helps
+            // if the advisor loads, so the inert posture is established here at install time too.
+            try {
+                applyGuardConfig(false);
+            } catch (error) {
+                console.log(`SpecPi: could not write the Jev guard's inert settings: ${error.message}`);
+            }
+
             packageState = {
                 basePackages,
                 packagesKeyBeforeExists: Object.hasOwn(before, "packages"),

package/templates/settings.json

@@ -6,6 +6,7 @@
         "npm:specpi-experiments@0.1.0",
         "npm:pi-goal-x@0.31.2",
         "npm:@sreetej510/pi-usage@0.10.0",
-        "npm:@gotgenes/pi-permission-system@32.0.2"
+        "npm:@gotgenes/pi-permission-system@32.0.2",
+        "npm:specpi-jev-guard@0.1.0"
     ]
 }