pi-adaptive-thinking 0.1.2 → 0.2.0

package/README.md

@@ -6,7 +6,7 @@ Bring adaptive reasoning-effort control to Pi agents.
 
 </div>
 
-`pi-adaptive-thinking` is a Pi extension that lets the agent change Pi's thinking level through a tool named `set_thinking_level`.
+`pi-adaptive-thinking` is a Pi extension that lets the agent inspect and change Pi's thinking level through tools named `get_thinking_level` and `set_thinking_level`.
 
 Requires Node `>=22.19.0` and Pi `>=0.84.1`.
 
@@ -27,7 +27,9 @@ pi -e ./src/index.ts
 
 ## Behavior
 
-The extension registers a tool with these parameters:
+The extension registers two tools. `get_thinking_level` returns the current native Pi thinking level and the levels supported by the selected model. The agent should inspect status only when the level is uncertain, not poll it every turn.
+
+`set_thinking_level` accepts these parameters:
 
 - `level`: one of the valid Pi thinking levels for the current model.
 - `persist`: optional boolean, default `false`.
@@ -48,6 +50,8 @@ Persistent changes:
 
 This changes the session baseline until another persistent change is made or the user changes thinking level manually.
 
+The extension contributes only static tool guidance to Pi's base prompt. It never replaces the per-turn system prompt, so current level, supported levels, model, and session state cannot invalidate the system-prompt cache prefix.
+
 ## Configuration
 
 Configuration files are loaded in this order:
@@ -64,10 +68,15 @@ Project configuration takes precedence over global configuration.
   "quiet": false,
   "toolName": "set_thinking_level",
   "toolDescription": "Set your thinking level",
-  "systemPrompt": "You MUST manage thinking level actively. Lower it before trivial or routine turns; raise it for ambiguity, debugging, risky changes, or multi-step synthesis. Reassess at turn start, after meaningful new evidence, and when the task shifts. NEVER leave the current level unchanged by inertia, and NEVER reply to a trivial turn before considering a downshift."
+  "statusToolName": "get_thinking_level",
+  "guidance": "You MUST manage thinking level actively. Lower it before trivial or routine turns; raise it for ambiguity, debugging, risky changes, or multi-step synthesis. Reassess at turn start, after meaningful new evidence, and when the task shifts. NEVER leave the current level unchanged by inertia, and NEVER reply to a trivial turn before considering a downshift."
 }
 ```
 
+`guidance`, tool names, and tool descriptions are loaded once per session and remain static. Do not put runtime state in `guidance`.
+
+The former `systemPrompt` field remains a deprecated alias for `guidance` during the `0.x` release line. Existing configurations continue to work and produce one UI warning at session start unless `quiet` is enabled. A configuration containing both fields is invalid.
+
 ## Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-adaptive-thinking",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "private": false,
   "description": "Pi extension for adaptive reasoning-effort control",
   "keywords": [

package/src/config-loader.ts

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { parseConfig, type AdaptiveThinkingConfig } from "./config.js";
+import { parseConfig, usesDeprecatedSystemPrompt, type AdaptiveThinkingConfig } from "./config.js";
 
 export type { AdaptiveThinkingConfig } from "./config.js";
 
@@ -11,7 +11,12 @@ export type LoadConfigOptions = {
 };
 
 export type LoadConfigResult =
-  | { success: true; config: AdaptiveThinkingConfig; source?: string }
+  | {
+      success: true;
+      config: AdaptiveThinkingConfig;
+      source?: string;
+      usedDeprecatedSystemPrompt?: true;
+    }
   | { success: false; source: string; error: Error };
 
 const hasCode = (error: unknown, code: string) => {
@@ -45,7 +50,13 @@ export const loadConfig = async ({
     }
 
     try {
-      return { success: true, source, config: parseConfig(JSON.parse(raw)) };
+      const input: unknown = JSON.parse(raw);
+      return {
+        success: true,
+        source,
+        config: parseConfig(input),
+        ...(usesDeprecatedSystemPrompt(input) ? { usedDeprecatedSystemPrompt: true as const } : {}),
+      };
     } catch (error) {
       return invalidConfig(source, error);
     }

package/src/config.ts

@@ -1,34 +1,72 @@
-import { Type, type Static } from "typebox";
+import { Type } from "typebox";
 import { Parse } from "typebox/value";
 
-export const defaultSystemPrompt =
+export const defaultGuidance =
   "You MUST manage thinking level actively. " +
   "Lower it before trivial or routine turns; raise it for ambiguity, debugging, risky changes, or multi-step synthesis. " +
   "Reassess at turn start, after meaningful new evidence, and when the task shifts. " +
   "NEVER leave the current level unchanged by inertia, and NEVER reply to a trivial turn before considering a downshift.";
 
-export const configDefaults = {
+export type AdaptiveThinkingConfig = {
+  enabled: boolean;
+  quiet: boolean;
+  toolName: string;
+  toolDescription: string;
+  statusToolName: string;
+  guidance: string;
+};
+
+export const configDefaults: AdaptiveThinkingConfig = {
   enabled: true,
   quiet: false,
   toolName: "set_thinking_level",
   toolDescription: "Set your thinking level",
-  systemPrompt: defaultSystemPrompt,
+  statusToolName: "get_thinking_level",
+  guidance: defaultGuidance,
 };
 
-export const ConfigSchema = Type.Object(
+const ConfigInputSchema = Type.Object(
   {
     enabled: Type.Boolean(),
     quiet: Type.Boolean(),
     toolName: Type.String({ minLength: 1 }),
     toolDescription: Type.String({ minLength: 1 }),
-    systemPrompt: Type.String({ minLength: 1 }),
+    statusToolName: Type.String({ minLength: 1 }),
+    guidance: Type.Optional(Type.String({ minLength: 1 })),
+    systemPrompt: Type.Optional(Type.String({ minLength: 1 })),
   },
   { additionalProperties: false },
 );
 
-export type AdaptiveThinkingConfig = Static<typeof ConfigSchema>;
+const hasOwnProperty = (input: unknown, property: string) =>
+  typeof input === "object" &&
+  input !== null &&
+  Object.prototype.hasOwnProperty.call(input, property);
+
+/** Returns whether raw configuration uses the deprecated system prompt alias. */
+export const usesDeprecatedSystemPrompt = (input: unknown) => hasOwnProperty(input, "systemPrompt");
 
+/** Parses configuration and normalizes legacy system prompt guidance. */
 export const parseConfig = (input: unknown): AdaptiveThinkingConfig => {
-  const merged = input === undefined ? configDefaults : { ...configDefaults, ...input };
-  return Parse(ConfigSchema, merged);
+  const usesGuidance = hasOwnProperty(input, "guidance");
+  const usesSystemPrompt = usesDeprecatedSystemPrompt(input);
+  if (usesGuidance && usesSystemPrompt) {
+    throw new Error(
+      "Adaptive Thinking configuration cannot contain both guidance and systemPrompt",
+    );
+  }
+
+  const rawInput = input as Record<string, unknown> | undefined;
+  const merged = {
+    ...configDefaults,
+    ...rawInput,
+    guidance: usesSystemPrompt ? rawInput?.systemPrompt : (rawInput?.guidance ?? defaultGuidance),
+  };
+  delete (merged as Record<string, unknown>).systemPrompt;
+
+  const config = Parse(ConfigInputSchema, merged) as AdaptiveThinkingConfig;
+  if (config.toolName === config.statusToolName) {
+    throw new Error("Adaptive Thinking toolName and statusToolName must be different");
+  }
+  return config;
 };

package/src/index.ts

@@ -4,8 +4,6 @@ import { join } from "node:path";
 import lockfile from "proper-lockfile";
 import type {
   AgentToolResult,
-  BeforeAgentStartEvent,
-  BeforeAgentStartEventResult,
   ExtensionAPI,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
@@ -21,7 +19,6 @@ type NotifyType = "info" | "warning" | "error";
 
 type RuntimeState = {
   config: AdaptiveThinkingConfig;
-  currentLevel?: PiThinkingLevel;
   persistedLevel?: PiThinkingLevel;
   temporaryResetLevel?: PiThinkingLevel;
   lastToolCallWasReasoningTool?: boolean;
@@ -48,11 +45,31 @@ const ToolParameters = Type.Object(
 
 type ToolParameters = Static<typeof ToolParameters>;
 
+const StatusToolParameters = Type.Object({}, { additionalProperties: false });
+
+type ThinkingLevelStatus = {
+  currentLevel: PiThinkingLevel | "unknown";
+  supportedLevels: PiThinkingLevel[];
+};
+
 const textResult = (text: string): AgentToolResult<undefined> => ({
   content: [{ type: "text", text }],
   details: undefined,
 });
 
+const thinkingLevelStatusResult = (
+  currentLevel: PiThinkingLevel | "unknown",
+  supportedLevels: PiThinkingLevel[],
+): AgentToolResult<ThinkingLevelStatus> => ({
+  content: [
+    {
+      type: "text",
+      text: `Current thinking level: ${currentLevel}. Supported thinking levels: ${supportedLevels.join(", ")}.`,
+    },
+  ],
+  details: { currentLevel, supportedLevels },
+});
+
 const errorMessage = (error: unknown) => (error instanceof Error ? error.message : String(error));
 
 const agentDir = () => process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
@@ -156,30 +173,6 @@ const notify = (
   ctx.ui.notify(message, type);
 };
 
-const appendSystemPromptBlock = (systemPrompt: string, block: string) => {
-  const trimmedBlock = block.trim();
-  if (!trimmedBlock) return systemPrompt;
-  if (!systemPrompt.trim()) return trimmedBlock;
-  return `${systemPrompt.trimEnd()}\n\n${trimmedBlock}`;
-};
-
-const formatGuidance = (
-  config: AdaptiveThinkingConfig,
-  currentLevel: string | undefined,
-  validLevels: string[],
-) => {
-  return (
-    config.systemPrompt.trim() +
-    " " +
-    (currentLevel ? `Current thinking level: ${currentLevel}. ` : "") +
-    `Valid thinking levels for this session: ${validLevels.join(", ")}. ` +
-    `To change the thinking level, use the \`${config.toolName}\` tool with one of the valid levels. ` +
-    "Only call it when the task complexity justifies changing levels. " +
-    `Do not call ${config.toolName} if the current thinking level already matches the target level. ` +
-    `Do not call ${config.toolName} twice in a row; reassess only after new evidence from other tool calls or user input.`
-  );
-};
-
 export default function adaptiveThinking(pi: ExtensionAPI) {
   let runtime: RuntimeState | undefined;
   let runtimeHandlersRegistered = false;
@@ -188,11 +181,6 @@ export default function adaptiveThinking(pi: ExtensionAPI) {
     if (runtimeHandlersRegistered) return;
     runtimeHandlersRegistered = true;
 
-    pi.on("thinking_level_select", async (event) => {
-      if (!runtime) return;
-      if (isThinkingLevel(event.level)) runtime.currentLevel = event.level;
-    });
-
     pi.on("tool_call", async (event) => {
       const state = runtime;
       if (!state) return;
@@ -208,8 +196,6 @@ export default function adaptiveThinking(pi: ExtensionAPI) {
       }
     });
 
-    pi.on("before_agent_start", async (event, ctx) => beforeAgentStart(event, ctx));
-
     pi.on("agent_end", async (_event, ctx) => {
       await resetTemporaryLevel(ctx);
       if (!runtime) return;
@@ -218,28 +204,6 @@ export default function adaptiveThinking(pi: ExtensionAPI) {
     });
   };
 
-  const beforeAgentStart = async (
-    event: BeforeAgentStartEvent,
-    ctx: ExtensionContext,
-  ): Promise<BeforeAgentStartEventResult> => {
-    const state = runtime;
-    if (!state) return { systemPrompt: event.systemPrompt };
-
-    state.lastToolCallWasReasoningTool = false;
-    state.reasoningToolCallBackToBackById.clear();
-
-    const currentLevel = state.currentLevel ?? pi.getThinkingLevel();
-    if (isThinkingLevel(currentLevel)) state.currentLevel = currentLevel;
-
-    const validLevels = resolveSupportedThinkingLevels(ctx.model);
-    return {
-      systemPrompt: appendSystemPromptBlock(
-        event.systemPrompt,
-        formatGuidance(state.config, state.currentLevel, validLevels),
-      ),
-    };
-  };
-
   const resetTemporaryLevel = async (ctx: ExtensionContext) => {
     const state = runtime;
     const resetLevel = state?.temporaryResetLevel;
@@ -247,7 +211,6 @@ export default function adaptiveThinking(pi: ExtensionAPI) {
 
     try {
       withSessionOnlyThinkingLevelChange(() => pi.setThinkingLevel(resetLevel));
-      state.currentLevel = resetLevel;
       delete state.temporaryResetLevel;
     } catch (error) {
       notify(ctx, "error", `Failed to reset thinking level: ${errorMessage(error)}`, state.config);
@@ -268,9 +231,16 @@ export default function adaptiveThinking(pi: ExtensionAPI) {
       return;
     }
 
-    const initialLevel = pi.getThinkingLevel();
     runtime = { config, reasoningToolCallBackToBackById: new Map() };
-    if (isThinkingLevel(initialLevel)) runtime.currentLevel = initialLevel;
+
+    if (configResult.usedDeprecatedSystemPrompt) {
+      notify(
+        ctx,
+        "warning",
+        "Adaptive Thinking configuration: systemPrompt is deprecated; rename it to guidance.",
+        config,
+      );
+    }
 
     pi.registerTool({
       name: config.toolName,
@@ -278,7 +248,10 @@ export default function adaptiveThinking(pi: ExtensionAPI) {
       description: config.toolDescription,
       promptSnippet: "Set the current Pi thinking level.",
       promptGuidelines: [
+        config.guidance,
         `Use ${config.toolName} to change the thinking level when task complexity justifies a different level.`,
+        `Use ${config.statusToolName} only when the current or supported thinking levels are uncertain; do not poll it routinely.`,
+        `Do not call ${config.toolName} twice in a row; reassess only after new evidence from other tool calls or user input.`,
       ],
       parameters: ToolParameters,
       execute: async (toolCallId, params: ToolParameters, _signal, _onUpdate, ctx) => {
@@ -294,7 +267,7 @@ export default function adaptiveThinking(pi: ExtensionAPI) {
         }
 
         const persist = params.persist ?? false;
-        const currentLevel = state.currentLevel ?? pi.getThinkingLevel();
+        const currentLevel = pi.getThinkingLevel();
         if (currentLevel === level) {
           return textResult(`Thinking level is already ${level}; no change made.`);
         }
@@ -308,13 +281,18 @@ export default function adaptiveThinking(pi: ExtensionAPI) {
         const resetLevel =
           state.persistedLevel ?? (isThinkingLevel(currentLevel) ? currentLevel : undefined);
 
+        if (!persist && !resetLevel) {
+          return textResult(
+            "Cannot apply a temporary thinking level because the Session Baseline is unknown.",
+          );
+        }
+
         try {
           withSessionOnlyThinkingLevelChange(() => pi.setThinkingLevel(level));
         } catch (error) {
           return textResult(`Failed to set thinking level: ${errorMessage(error)}`);
         }
 
-        state.currentLevel = level;
         if (persist) {
           state.persistedLevel = level;
           delete state.temporaryResetLevel;
@@ -328,6 +306,24 @@ export default function adaptiveThinking(pi: ExtensionAPI) {
       },
     });
 
+    pi.registerTool({
+      name: config.statusToolName,
+      label: "Get Thinking Level",
+      description: "Get the current and supported Pi thinking levels",
+      promptSnippet: "Inspect the current and supported Pi thinking levels.",
+      promptGuidelines: [
+        `Use ${config.statusToolName} only when thinking-level state is uncertain; do not poll it routinely.`,
+      ],
+      parameters: StatusToolParameters,
+      execute: async (_toolCallId, _params, _signal, _onUpdate, ctx) => {
+        const currentLevel = pi.getThinkingLevel();
+        return thinkingLevelStatusResult(
+          isThinkingLevel(currentLevel) ? currentLevel : "unknown",
+          resolveSupportedThinkingLevels(ctx.model),
+        );
+      },
+    });
+
     registerRuntimeHandlers();
   });
 }