specpi 0.30.1 → 0.32.0

package/extensions/workflow-controls/index.ts

@@ -5,8 +5,10 @@ import { truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import {
     CAPABILITY_NAMES,
+    CAPABILITY_REQUEST_TOOL,
     capabilityActive,
     capabilityInstalled,
+    capabilityRequestOffered,
     describeCapabilities,
     findCapability,
     missingTools,
@@ -389,6 +391,17 @@ export default function workflowControls(pi: ExtensionAPI) {
         );
     });
 
+    // Decided once per session, before the first request, so the cached prompt prefix is never
+    // disturbed. See capabilityRequestOffered for why a session may not need the tool at all.
+    const applyCapabilityRequest = (ctx: ExtensionContext) => {
+        const allToolNames = typeof pi.getAllTools === "function" ? pi.getAllTools().map((tool) => tool.name) : [];
+        syncToolGroup(
+            pi,
+            [CAPABILITY_REQUEST_TOOL],
+            capabilityRequestOffered({ interactive: ctx.hasUI, allToolNames }),
+        );
+    };
+
     // Web access ships hidden. A missing or unreadable preference means off, and the
     // gate only ever touches its own four tool names.
     let webAccessEnabled = loadStartupActivation();
@@ -397,6 +410,7 @@ export default function workflowControls(pi: ExtensionAPI) {
     pi.on("session_start", (_event, ctx) => {
         webAccessEnabled = loadStartupActivation();
         applyWebAccess();
+        applyCapabilityRequest(ctx);
         beginRestore(ctx);
     });
 
@@ -561,7 +575,7 @@ export default function workflowControls(pi: ExtensionAPI) {
         if (scope.active) {
             const taskStale = scope.taskDigest !== undefined && currentTask?.digest !== scope.taskDigest;
             guidance.push(
-                `[SPECPI SCOPE]\nDeclared paths: ${scope.entries.map((item) => `${sanitizePathLabel(item.path)}${item.directory ? "/" : ""}`).join(", ")}\nPending outside-scope paths: ${scope.pending.map(sanitizePathLabel).join(", ") || "none"}. Do not describe pending paths as accepted scope.${taskStale ? "\nTask-bound scope is stale; do not widen it automatically." : ""}`,
+                `[SPECPI SCOPE]\nDeclared paths: ${scope.entries.map((item) => `${sanitizePathLabel(item.path)}${item.directory ? "/" : ""}`).join(", ")}\nPending outside-scope paths: ${scope.pending.map(sanitizePathLabel).join(", ") || "none"}. Keep outside-scope findings pending until the human allows once, acknowledges them with /scope accept, expands scope with /scope add, or clears it. Acknowledgement does not widen scope, and pending paths are not accepted scope.${taskStale ? "\nTask-bound scope is stale; do not widen it automatically." : ""}`,
             );
         }
 
@@ -905,9 +919,9 @@ export default function workflowControls(pi: ExtensionAPI) {
     };
 
     pi.registerTool({
-        name: "request_capability",
+        name: CAPABILITY_REQUEST_TOOL,
         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, 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.`,
+        description: `Ask the user to restore a withdrawn tool group for this session — ${describeCapabilities()}. Hidden tools cannot be called until restored. Ask only when the task needs one: restoring mid-session discards the cached prompt prefix, about 20% of a mid-length task's cost. Restored tools work from your next message; if the user declines, continue without them. Delegation is not requestable; ask the user to run /delegate on.`,
         parameters: Type.Object(
             {
                 capability: StringEnum(CAPABILITY_NAMES, {

package/package.json

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

package/scripts/specpi.mjs

@@ -62,7 +62,6 @@ const resourcePaths = [
     "extensions/jev-advisor/questions/retention.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",

package/skills/specpi-improve/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: specpi-improve
 description: Turns a selected SpecPi capability-gap wishlist item into a minimal, evidence-backed, reversible improvement. Use when the user asks to improve SpecPi from its wishlist, act on a selected gap, or complete the notice-to-retire loop.
+disable-model-invocation: true
 ---
 
 # SpecPi Improve

package/templates/AGENTS.md

@@ -2,11 +2,7 @@
 
 - Keep changes small, testable, reversible, and tied to the human's request. Inspect existing code and guidance before editing; avoid adjacent feature accumulation.
 - Prefer direct work and existing project tools. Ask concise questions only when material requirements are unclear.
-- Keep replies brief and human-readable. Lead with the answer, use plain language, and avoid jargon, technical babble, and repetitive progress updates. Include technical detail only when it helps the human decide or act.
-- Write commits and pull requests the same way: a short, clear title and a brief explanation of what changed, why, and what was tested. Avoid boilerplate, inflated claims, and unnecessary implementation detail.
-- When `/scope` is active, keep outside-scope findings pending until the human allows once, acknowledges them with `/scope accept`, expands scope with `/scope add`, or clears it. Acknowledgement does not widen scope.
-- Treat wishlist observations as leads, not authorization. Start a wishlist-sourced change only from an exact `/harness-improvement` selection and follow `specpi-improve`. Record its contract before editing and retire only after its verification gate passes.
-- Web access and Browser QA tools ship hidden to keep each request small. When the task genuinely needs one, call `request_capability`; it asks the human, who may decline. Continue without the capability if they do, and do not attempt a hidden tool. The human can also run `/webaccess on` or `/browser on` directly. Delegation is not requestable this way; ask the human to run `/delegate on`.
-- Never inspect Pi authentication, provider credentials, trust decisions, sessions, missions, or history to improve the harness. Use only the active extension context and intended local improvement records.
+- Keep replies brief and human-readable: lead with the answer, use plain language, avoid jargon and repetitive progress updates, and include technical detail only when it helps the human decide or act.
+- Write commits and pull requests the same way: a short, clear title and a brief note on what changed, why, and what was tested.
 - Use observed files, diffs, tests, and runtime behavior as evidence. Run relevant checks, inspect the final diff, and obtain fresh read-only review when risk warrants it. Report results and residual risks without claiming more than the checks prove.
 - Do not commit, push, publish, deploy, or alter remote state unless explicitly requested.

package/extensions/jev-advisor/questions/progress.mjs

@@ -1,195 +0,0 @@
-// System 5: notice that a session has stopped making progress, while it can still be helped.
-//
-// This is the only system aimed at turns rather than at input tokens, and turns are where the money
-// is on the hard tiers. Splitting recorded cost three ways: at tier 3 output is 59% of spend, at
-// tier 4 66%, at tier 5 56%. Output is bought by turns, and every other system here targets
-// input. At tier 4 `specpi-jev` runs cheaper per turn than `specpi-default` -- $0.000538 against
-// $0.000613 -- and costs more per attempt anyway, because it takes 29.4 turns against 24.8.
-//
-// The evidence that turns are wasted rather than merely numerous is in the same runs.
-// `specpi-default` invoked `webqa` 199 times across 30 turns on `t4-browser-triage` and still
-// failed. Pi stock abandoned after two tries and burned the full 600-second timeout on two tier-4
-// tasks, scoring zero both times. A turn costs 4-7 seconds and $0.0005-$0.0011; a Jev call costs
-// about 300ms and $0.0000105. Preventing one timeout pays for roughly two thousand calls.
-//
-// LOCAL STATE FIRST, which is the standing rule and the reason this is affordable. Local state
-// cannot answer "is this session stuck" -- that needs a judgement about whether the work is going
-// anywhere -- but it answers "is that question worth asking", and it answers it cheaply. Nothing is
-// sent unless a repeated tool signature, a run of errors or a stretch of turns without a file
-// change has already made the session look suspicious.
-//
-// It is an append, so it passes the standing cache rule: the line goes on the end of the transcript
-// at a turn boundary and invalidates no prefix. It is written once and never retracted, because
-// retracting it would mean rewriting the thing it was appended to.
-//
-// The plan named `deliverAs: "nextTurn"` for that append. Pi documents that mode as "queued for
-// next user prompt, does not interrupt or trigger anything", and an unattended session has exactly
-// one user prompt -- so a nextTurn message would never arrive, in precisely the case the argument
-// for this system rests on. The caller uses "steer" instead: delivered after the current tool calls
-// finish and before the next model request, which is the same append at the same boundary and is
-// actually read. `triggerTurn` stays off, so this can never add a turn of its own.
-
-import { choice, noul } from "../client.mjs";
-import { choiceValue, nounTrue } from "../gate.mjs";
-import { compact } from "../sanitize.mjs";
-
-/**
- * The same taxonomy `scripts/jev-triage.mjs` uses offline. It lives here, in the shipped extension,
- * and the script imports it: the corpus that calibrates this system and the enum this system asks
- * against have to be the same object, or the published failure-mode distribution is measuring
- * something the session never asks.
- */
-export const FAILURE_MODES = Object.freeze({
-    "gave-up-on-fault": "Met an injected command failure and stopped instead of retrying",
-    "turn-cap": "Ran out of turns or requests while still working",
-    timeout: "Exceeded the wall-clock limit",
-    "wrong-approach": "Worked steadily but solved the wrong problem",
-    "misread-requirement": "Produced output that misses a stated requirement",
-    "scope-violation": "Changed files it was told to leave alone",
-    "tool-error-loop": "Repeated the same failing tool call without progress",
-    "harness-error": "The harness itself crashed or could not start",
-    unknown: "Not determinable from what was recorded",
-});
-
-/** Modes a session can still act on. A timeout or a crashed harness is not advice, it is an epitaph. */
-export const ACTIONABLE_MODES = Object.freeze(
-    new Set(["wrong-approach", "misread-requirement", "tool-error-loop", "gave-up-on-fault", "scope-violation"]),
-);
-
-/** Tools whose success means the worktree changed. Used only to decide whether anything happened. */
-export const MUTATING_TOOLS = Object.freeze(
-    new Set(["write", "edit", "multi_edit", "apply_patch", "create_file", "str_replace"]),
-);
-
-/** Turns without a single successful mutation before that counts as a reason to look. */
-export const STALE_TURNS = 4;
-const REPEAT_SIGNATURES = 2;
-const CONSECUTIVE_ERRORS = 3;
-
-/**
- * Turns to stay quiet after asking. Conditions persist for many turns at a time, so without this
- * the same unchanged situation is re-asked every turn until the budget runs out.
- */
-export const ASK_COOLDOWN_TURNS = 4;
-
-/**
- * A tool call reduced to something comparable. The arguments matter -- reading two different files
- * twice is work, reading one file twice is a loop -- but their contents do not, so this keeps a
- * short normalized form rather than the payload.
- */
-export function signature(toolName, input) {
-    return compact(`${toolName}:${JSON.stringify(input ?? {})}`, 120);
-}
-
-/**
- * Whether local state alone already justifies the question. Returns the reasons rather than a bare
- * boolean, because they go into the state as the grounds for asking and a caller logging "asked"
- * without "why" cannot audit the budget afterwards.
- *
- * One reason is not enough, and that is a correction rather than a precaution. The first version
- * asked whenever any single signal fired, and a live run of `t3-cascade-ledger` spent all twelve
- * calls of its budget on a session that finished with a score of 0.978. A 120-step repair chain
- * re-runs the same verification command constantly, so "a tool signature repeated" is its normal
- * condition, not a symptom. The same is true of "no file written for four turns" during a long
- * read: a research task looks identical to a stuck one from that signal alone.
- *
- * So a repeated call or a quiet stretch must coincide with something else before it is worth
- * asking about. A run of consecutive errors stands alone, because nothing healthy produces three
- * failures in a row.
- */
-export function suspicious(history) {
-    const reasons = [];
-    const signatures = history?.signatures ?? [];
-    const counts = new Map();
-    for (const item of signatures) {
-        counts.set(item, (counts.get(item) ?? 0) + 1);
-    }
-
-    const repeated = [...counts.entries()].filter(([, count]) => count >= REPEAT_SIGNATURES);
-    if (repeated.length > 0) {
-        reasons.push("repeated-tool-call");
-    }
-
-    const errors = (history?.consecutiveErrors ?? 0) >= CONSECUTIVE_ERRORS;
-    if (errors) {
-        reasons.push("consecutive-errors");
-    }
-
-    if ((history?.turnsSinceChange ?? 0) >= STALE_TURNS) {
-        reasons.push("no-file-change");
-    }
-
-    // Conditions persist across turns, so a verdict of "not stuck" is still the right answer three
-    // turns later and asking again buys nothing. The cooldown is what stops one situation being
-    // charged for repeatedly.
-    const cooling = Number.isFinite(history?.askedAtTurn)
-        ? (history.turn ?? 0) - history.askedAtTurn < ASK_COOLDOWN_TURNS
-        : false;
-
-    return {
-        ask: !cooling && (errors || reasons.length >= 2),
-        reasons,
-        repeatedSignatures: repeated.length,
-        cooling,
-    };
-}
-
-/** Shape and counts. No tool output, no file contents, no arguments beyond a normalized signature. */
-export function buildInput({ history, objective, reasons }) {
-    return {
-        objective: compact(objective ?? "", 180),
-        turn: history?.turn ?? 0,
-        reasons,
-        turnsSinceFileChange: history?.turnsSinceChange ?? 0,
-        consecutiveErrors: history?.consecutiveErrors ?? 0,
-        distinctTools: [...new Set((history?.tools ?? []).slice(-12))].slice(0, 12),
-        repeatedCalls: suspicious(history).repeatedSignatures,
-        recentErrors: (history?.errors ?? []).slice(-4).map((item) => compact(item, 80)),
-        filesChanged: history?.filesChanged ?? 0,
-    };
-}
-
-export function questions() {
-    return {
-        // Deliberately two questions rather than one. "Is it stuck" is the decision; "which mode"
-        // is what makes a fixed remedy line possible without any model-written prose.
-        is_stuck: noul("This session has stopped making progress and will not finish without changing approach"),
-        failure_mode: choice("If this session is going to fail, why?", FAILURE_MODES),
-        needs_human: noul("A person would have to answer something before this session could continue"),
-    };
-}
-
-/** One fixed line per mode. Code-written, so nothing the model produced reaches the transcript. */
-const REMEDIES = Object.freeze({
-    "wrong-approach":
-        "Progress check: the last few turns have not moved the task forward. Re-read the objective and state, in one line, what the current approach is meant to achieve before continuing.",
-    "misread-requirement":
-        "Progress check: the work so far may not match what was asked. Re-read the requirements and list which ones are satisfied and which are not, before making further changes.",
-    "tool-error-loop":
-        "Progress check: the same tool call has failed repeatedly. Stop retrying it and either fix the cause or use a different approach.",
-    "gave-up-on-fault":
-        "Progress check: a command failed and was not retried. Transient failures are expected here; retry it before concluding the task cannot be done.",
-    "scope-violation":
-        "Progress check: files outside the permitted scope may have been changed. Check what has been modified against what the task allows.",
-});
-
-/**
- * The nudge, or nothing. Requires a confident stuck verdict AND a gated mode with a remedy: a
- * confident "stuck" with no idea why would produce a message that says only that something is
- * wrong, which is the kind of unfalsifiable hint the standing rule against risk hints rejects.
- *
- * `needsHuman` decides who the nudge is for. If the session is blocked on something only a person
- * can answer -- a missing credential, an ambiguous requirement -- then telling the model to try
- * harder is the wrong recipient and costs a turn to say nothing. The caller reads it to suppress
- * the message path while still surfacing the notification.
- */
-export function decide(answers) {
-    const stuck = nounTrue(answers?.is_stuck, "progress");
-    const mode = choiceValue(answers?.failure_mode, "progress");
-    const needsHuman = nounTrue(answers?.needs_human, "progress");
-    if (!stuck || !mode || !ACTIONABLE_MODES.has(mode) || !REMEDIES[mode]) {
-        return { nudge: undefined, stuck, mode, needsHuman };
-    }
-
-    return { nudge: REMEDIES[mode], stuck, mode, needsHuman };
-}