pi-adaptive-thinking 0.1.2 → 0.2.1

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.1",
   "private": false,
   "description": "Pi extension for adaptive reasoning-effort control",
   "keywords": [

package/src/adaptive-thinking-lifecycle.ts

@@ -0,0 +1,395 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import lockfile from "proper-lockfile";
+import type {
+  AgentEndEvent,
+  AgentToolResult,
+  ExtensionAPI,
+  ExtensionContext,
+  SessionStartEvent,
+  ToolCallEvent,
+  ToolCallEventResult,
+  ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { Parse } from "typebox/value";
+import { loadConfig, type AdaptiveThinkingConfig } from "./config-loader.js";
+import {
+  isThinkingLevel,
+  resolveSupportedThinkingLevels,
+  type PiThinkingLevel,
+} from "./thinking-levels.js";
+
+type NotifyType = "info" | "warning" | "error";
+
+type RuntimeState = {
+  config: AdaptiveThinkingConfig;
+  persistedLevel?: PiThinkingLevel;
+  temporaryResetLevel?: PiThinkingLevel;
+  lastToolCallWasReasoningTool?: boolean;
+  reasoningToolCallBackToBackById: Map<string, boolean>;
+};
+
+const ToolParameters = Type.Object(
+  {
+    level: Type.String({
+      minLength: 1,
+      description:
+        "The Pi thinking level to apply. Higher levels may improve hard-task quality but may take more time and resources.",
+    }),
+    persist: Type.Optional(
+      Type.Boolean({
+        default: false,
+        description:
+          "Whether to persist the setting for this session; otherwise it applies only for the current turn.",
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+type ToolParameters = Static<typeof ToolParameters>;
+
+const StatusToolParameters = Type.Object({}, { additionalProperties: false });
+
+type ThinkingLevelStatus = {
+  currentLevel: PiThinkingLevel | "unknown";
+  supportedLevels: PiThinkingLevel[];
+};
+
+/** The extension-context fields Adaptive Thinking reads at its lifecycle and tool seams. */
+export type AdaptiveThinkingContext = {
+  readonly cwd: string;
+  readonly hasUI: boolean;
+  readonly model: ExtensionContext["model"];
+  readonly ui: Pick<ExtensionContext["ui"], "notify">;
+};
+
+type AdaptiveThinkingHandler<Event, Result = undefined> = (
+  event: Event,
+  context: AdaptiveThinkingContext,
+) => Promise<Result | void> | Result | void;
+
+type AdaptiveThinkingToolExecution<Args, Details> = (
+  toolCallId: string,
+  parameters: Args,
+  signal: AbortSignal | undefined,
+  onUpdate: globalThis.Parameters<ToolDefinition<typeof ToolParameters, Details>["execute"]>[3],
+  context: AdaptiveThinkingContext,
+) => Promise<AgentToolResult<Details>>;
+
+/** Set-thinking-level parameters accepted after Pi has validated the tool schema. */
+export type AdaptiveThinkingSetThinkingLevelParameters = Static<typeof ToolParameters>;
+
+/** Current and supported thinking levels returned by the status tool. */
+export type AdaptiveThinkingLevelStatus = ThinkingLevelStatus;
+
+type SetThinkingLevelTool = Omit<ToolDefinition<typeof ToolParameters, undefined>, "execute"> & {
+  execute: AdaptiveThinkingToolExecution<AdaptiveThinkingSetThinkingLevelParameters, undefined>;
+};
+type GetThinkingLevelTool = Omit<
+  ToolDefinition<typeof StatusToolParameters, ThinkingLevelStatus>,
+  "execute"
+> & {
+  execute: AdaptiveThinkingToolExecution<Record<string, never>, ThinkingLevelStatus>;
+};
+
+/** Tool definitions registered by the Adaptive Thinking extension. */
+export type AdaptiveThinkingToolDefinition = SetThinkingLevelTool | GetThinkingLevelTool;
+
+/** Identifies the set-thinking-level tool without relying on its configurable name. */
+export const isAdaptiveThinkingSetThinkingLevelTool = (
+  tool: AdaptiveThinkingToolDefinition,
+): tool is SetThinkingLevelTool => tool.parameters === ToolParameters;
+
+/** Identifies the status tool without relying on its configurable name. */
+export const isAdaptiveThinkingStatusTool = (
+  tool: AdaptiveThinkingToolDefinition,
+): tool is GetThinkingLevelTool => tool.parameters === StatusToolParameters;
+
+/** Minimal Pi host capability required by the Adaptive Thinking extension. */
+export type AdaptiveThinkingExtensionHost = {
+  onSessionStart(handler: AdaptiveThinkingHandler<SessionStartEvent>): void;
+  onToolCall(handler: AdaptiveThinkingHandler<ToolCallEvent, ToolCallEventResult>): void;
+  onAgentEnd(handler: AdaptiveThinkingHandler<AgentEndEvent>): void;
+  registerTool(tool: AdaptiveThinkingToolDefinition): void;
+  getThinkingLevel(): string;
+  setThinkingLevel(level: PiThinkingLevel): void;
+};
+
+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 = (cause: Error) => cause.message;
+
+const SettingsDocumentSchema = Type.Object(
+  { defaultThinkingLevel: Type.Optional(Type.String()) },
+  { additionalProperties: Type.Unknown() },
+);
+
+const agentDir = () => process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+
+const globalSettingsPath = () => join(agentDir(), "settings.json");
+
+const withSettingsLock = async <T>(settingsPath: string, fn: () => Promise<T> | T): Promise<T> => {
+  mkdirSync(join(settingsPath, ".."), { recursive: true });
+  const lockPath = `${settingsPath}.adaptive-thinking`;
+  if (!existsSync(lockPath)) writeFileSync(lockPath, "");
+
+  const release = await lockfile.lock(lockPath, {
+    realpath: false,
+    retries: { retries: 99, factor: 1, minTimeout: 20, maxTimeout: 20 },
+  });
+
+  try {
+    return await fn();
+  } finally {
+    await release();
+  }
+};
+
+const readDefaultThinkingLevel = (settingsPath: string): PiThinkingLevel | undefined => {
+  if (!existsSync(settingsPath)) return undefined;
+
+  try {
+    const settings = Parse(SettingsDocumentSchema, JSON.parse(readFileSync(settingsPath, "utf-8")));
+    const level = settings.defaultThinkingLevel;
+    return level !== undefined && isThinkingLevel(level) ? level : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const restoreDefaultThinkingLevel = (
+  settingsPath: string,
+  previousDefaultThinkingLevel: PiThinkingLevel | undefined,
+) => {
+  if (!existsSync(settingsPath)) return;
+
+  try {
+    const settings = Parse(SettingsDocumentSchema, JSON.parse(readFileSync(settingsPath, "utf-8")));
+    if (previousDefaultThinkingLevel === undefined) {
+      delete settings.defaultThinkingLevel;
+    } else {
+      settings.defaultThinkingLevel = previousDefaultThinkingLevel;
+    }
+    writeFileSync(settingsPath, JSON.stringify(settings, undefined, 2) + "\n");
+  } catch {
+    return;
+  }
+};
+
+const withSessionOnlyThinkingLevelChange = async (changeThinkingLevel: () => void) => {
+  const settingsPath = globalSettingsPath();
+
+  await withSettingsLock(settingsPath, () => {
+    const previousDefaultThinkingLevel = readDefaultThinkingLevel(settingsPath);
+
+    changeThinkingLevel();
+
+    restoreDefaultThinkingLevel(settingsPath, previousDefaultThinkingLevel);
+  });
+};
+
+const notify = (
+  ctx: AdaptiveThinkingContext,
+  type: NotifyType,
+  message: string,
+  config?: Pick<AdaptiveThinkingConfig, "quiet">,
+) => {
+  if (config?.quiet) return;
+  if (!ctx.hasUI) return;
+  ctx.ui.notify(message, type);
+};
+
+/** Registers Adaptive Thinking against its narrow lifecycle, tool, and thinking-level host. */
+export function registerAdaptiveThinking(pi: AdaptiveThinkingExtensionHost) {
+  let runtime: RuntimeState | undefined;
+  let runtimeHandlersRegistered = false;
+
+  const registerRuntimeHandlers = () => {
+    if (runtimeHandlersRegistered) return;
+    runtimeHandlersRegistered = true;
+
+    pi.onToolCall(async (event) => {
+      const state = runtime;
+      if (!state) return;
+
+      if (event.toolName === state.config.toolName) {
+        state.reasoningToolCallBackToBackById.set(
+          event.toolCallId,
+          state.lastToolCallWasReasoningTool ?? false,
+        );
+        state.lastToolCallWasReasoningTool = true;
+      } else {
+        state.lastToolCallWasReasoningTool = false;
+      }
+    });
+
+    pi.onAgentEnd(async (_event, ctx) => {
+      await resetTemporaryLevel(ctx);
+      if (!runtime) return;
+      runtime.lastToolCallWasReasoningTool = false;
+      runtime.reasoningToolCallBackToBackById.clear();
+    });
+  };
+
+  const resetTemporaryLevel = async (ctx: AdaptiveThinkingContext) => {
+    const state = runtime;
+    const resetLevel = state?.temporaryResetLevel;
+    if (!state || !resetLevel) return;
+
+    try {
+      await withSessionOnlyThinkingLevelChange(() => pi.setThinkingLevel(resetLevel));
+      delete state.temporaryResetLevel;
+    } catch (cause) {
+      const error = cause instanceof Error ? cause : new Error(String(cause));
+      notify(ctx, "error", `Failed to reset thinking level: ${errorMessage(error)}`, state.config);
+    }
+  };
+
+  const registerSetThinkingLevelTool = (tool: SetThinkingLevelTool) => pi.registerTool(tool);
+  const registerGetThinkingLevelTool = (tool: GetThinkingLevelTool) => pi.registerTool(tool);
+
+  pi.onSessionStart(async (_event, ctx) => {
+    const configResult = await loadConfig({ cwd: ctx.cwd });
+    if (!configResult.success) {
+      runtime = undefined;
+      notify(ctx, "error", configResult.error.message);
+      return;
+    }
+
+    const { config } = configResult;
+    if (!config.enabled) {
+      runtime = undefined;
+      return;
+    }
+
+    runtime = { config, reasoningToolCallBackToBackById: new Map() };
+
+    if (configResult.usedDeprecatedSystemPrompt) {
+      notify(
+        ctx,
+        "warning",
+        "Adaptive Thinking configuration: systemPrompt is deprecated; rename it to guidance.",
+        config,
+      );
+    }
+
+    registerSetThinkingLevelTool({
+      name: config.toolName,
+      label: "Set Thinking Level",
+      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) => {
+        const state = runtime;
+        if (!state) return textResult("Adaptive Thinking is not enabled for this session.");
+
+        const level = params.level.trim();
+        const validLevels = resolveSupportedThinkingLevels(ctx.model);
+        if (!isThinkingLevel(level) || !validLevels.includes(level)) {
+          return textResult(
+            `Invalid thinking level: ${level}. Valid levels: ${validLevels.join(", ")}.`,
+          );
+        }
+
+        const persist = params.persist ?? false;
+        const currentLevel = pi.getThinkingLevel();
+        if (currentLevel === level) {
+          return textResult(`Thinking level is already ${level}; no change made.`);
+        }
+
+        if (state.reasoningToolCallBackToBackById.get(toolCallId) ?? false) {
+          return textResult(
+            `Thinking level change skipped because the previous tool call was also ${state.config.toolName}. Reassess after another tool call or new user input.`,
+          );
+        }
+
+        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 {
+          await withSessionOnlyThinkingLevelChange(() => pi.setThinkingLevel(level));
+        } catch (cause) {
+          const error = cause instanceof Error ? cause : new Error(String(cause));
+          return textResult(`Failed to set thinking level: ${errorMessage(error)}`);
+        }
+
+        if (persist) {
+          state.persistedLevel = level;
+          delete state.temporaryResetLevel;
+        } else if (resetLevel && resetLevel !== level) {
+          state.temporaryResetLevel = resetLevel;
+        } else {
+          delete state.temporaryResetLevel;
+        }
+
+        return textResult(`Thinking level set to ${level}`);
+      },
+    });
+
+    registerGetThinkingLevelTool({
+      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();
+  });
+}
+
+/** Adapts Pi's complete ExtensionAPI to the Adaptive Thinking lifecycle capability. */
+export default function adaptiveThinkingExtension(pi: ExtensionAPI) {
+  registerAdaptiveThinking({
+    onSessionStart: (handler) => pi.on("session_start", handler),
+    onToolCall: (handler) => pi.on("tool_call", handler),
+    onAgentEnd: (handler) => pi.on("agent_end", handler),
+    registerTool: (tool) => {
+      if (isAdaptiveThinkingSetThinkingLevelTool(tool)) pi.registerTool(tool);
+      else pi.registerTool(tool);
+    },
+    getThinkingLevel: () => pi.getThinkingLevel(),
+    setThinkingLevel: (level) => pi.setThinkingLevel(level),
+  });
+}

package/src/config-loader.ts

@@ -1,7 +1,11 @@
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { parseConfig, type AdaptiveThinkingConfig } from "./config.js";
+import {
+  parseAdaptiveThinkingConfig,
+  type AdaptiveThinkingConfig,
+  type ParsedAdaptiveThinkingConfig,
+} from "./config.js";
 
 export type { AdaptiveThinkingConfig } from "./config.js";
 
@@ -11,21 +15,32 @@ 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) => {
-  return typeof error === "object" && error !== null && "code" in error && error.code === code;
-};
-
-const errorMessage = (error: unknown) => (error instanceof Error ? error.message : String(error));
+const hasErrorCode = (cause: NodeJS.ErrnoException, code: string) =>
+  Object.hasOwn(cause, "code") && cause.code === code;
 
-const invalidConfig = (source: string, error: unknown): LoadConfigResult => ({
+const invalidConfig = (source: string, cause: Error): LoadConfigResult => ({
   success: false,
   source,
-  error: new Error(`Invalid Adaptive Thinking configuration in ${source}: ${errorMessage(error)}`),
+  error: new Error(`Invalid Adaptive Thinking configuration in ${source}: ${cause.message}`, {
+    cause,
+  }),
 });
 
+const readAdaptiveThinkingConfig = async (
+  source: string,
+): Promise<ParsedAdaptiveThinkingConfig> => {
+  const raw = await readFile(source, "utf8");
+  return parseAdaptiveThinkingConfig(JSON.parse(raw));
+};
+
 export const loadConfig = async ({
   cwd,
   homeDir = homedir(),
@@ -36,20 +51,26 @@ export const loadConfig = async ({
   ];
 
   for (const source of candidates) {
-    let raw: string;
+    let parsedConfig: ParsedAdaptiveThinkingConfig;
     try {
-      raw = await readFile(source, "utf8");
-    } catch (error) {
-      if (hasCode(error, "ENOENT")) continue;
+      parsedConfig = await readAdaptiveThinkingConfig(source);
+    } catch (cause) {
+      const error = cause instanceof Error ? cause : new Error(String(cause));
+      const fileSystemError: NodeJS.ErrnoException = error;
+      if (hasErrorCode(fileSystemError, "ENOENT")) continue;
       return invalidConfig(source, error);
     }
 
-    try {
-      return { success: true, source, config: parseConfig(JSON.parse(raw)) };
-    } catch (error) {
-      return invalidConfig(source, error);
+    const result: Extract<LoadConfigResult, { success: true }> = {
+      success: true,
+      source,
+      config: parsedConfig.config,
+    };
+    if (parsedConfig.usedDeprecatedSystemPrompt) {
+      result.usedDeprecatedSystemPrompt = true;
     }
+    return result;
   }
 
-  return { success: true, config: parseConfig(undefined) };
+  return { success: true, config: parseAdaptiveThinkingConfig(undefined).config };
 };

package/src/config.ts

@@ -1,34 +1,83 @@
-import { Type, type Static } from "typebox";
+import type { JsonValue } from "@earendil-works/pi-agent-core";
+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(
-  {
-    enabled: Type.Boolean(),
-    quiet: Type.Boolean(),
-    toolName: Type.String({ minLength: 1 }),
-    toolDescription: Type.String({ minLength: 1 }),
-    systemPrompt: Type.String({ minLength: 1 }),
-  },
+const ConfigValueSchema = Type.Object({
+  enabled: Type.Boolean(),
+  quiet: Type.Boolean(),
+  toolName: Type.String({ minLength: 1 }),
+  toolDescription: Type.String({ minLength: 1 }),
+  statusToolName: Type.String({ minLength: 1 }),
+  guidance: Type.String({ minLength: 1 }),
+});
+
+const ConfigOverridesSchema = Type.Partial(
+  Type.Intersect([
+    ConfigValueSchema,
+    Type.Object({ systemPrompt: Type.Optional(Type.String({ minLength: 1 })) }),
+  ]),
   { additionalProperties: false },
 );
 
-export type AdaptiveThinkingConfig = Static<typeof ConfigSchema>;
+/** Parsed configuration and metadata retained from the configuration ingress boundary. */
+export type ParsedAdaptiveThinkingConfig = {
+  config: AdaptiveThinkingConfig;
+  usedDeprecatedSystemPrompt: boolean;
+};
 
-export const parseConfig = (input: unknown): AdaptiveThinkingConfig => {
-  const merged = input === undefined ? configDefaults : { ...configDefaults, ...input };
-  return Parse(ConfigSchema, merged);
+/** Parses optional configuration values and normalizes the deprecated system prompt alias. */
+export const parseAdaptiveThinkingConfig = (
+  input: JsonValue | undefined,
+): ParsedAdaptiveThinkingConfig => {
+  const overrides = input === undefined ? {} : Parse(ConfigOverridesSchema, input);
+  const usesGuidance = overrides.guidance !== undefined;
+  const usesSystemPrompt = overrides.systemPrompt !== undefined;
+  if (usesGuidance && usesSystemPrompt) {
+    throw new Error(
+      "Adaptive Thinking configuration cannot contain both guidance and systemPrompt",
+    );
+  }
+
+  const guidance = overrides.guidance ?? overrides.systemPrompt ?? configDefaults.guidance;
+  const config: AdaptiveThinkingConfig = {
+    enabled: overrides.enabled ?? configDefaults.enabled,
+    quiet: overrides.quiet ?? configDefaults.quiet,
+    toolName: overrides.toolName ?? configDefaults.toolName,
+    toolDescription: overrides.toolDescription ?? configDefaults.toolDescription,
+    statusToolName: overrides.statusToolName ?? configDefaults.statusToolName,
+    guidance,
+  };
+  if (config.toolName === config.statusToolName) {
+    throw new Error("Adaptive Thinking toolName and statusToolName must be different");
+  }
+
+  return { config, usedDeprecatedSystemPrompt: usesSystemPrompt };
 };
+
+/** Parses configuration at the public configuration seam. */
+export const parseConfig = (input: JsonValue | undefined): AdaptiveThinkingConfig =>
+  parseAdaptiveThinkingConfig(input).config;

package/src/index.ts

@@ -1,333 +1 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import lockfile from "proper-lockfile";
-import type {
-  AgentToolResult,
-  BeforeAgentStartEvent,
-  BeforeAgentStartEventResult,
-  ExtensionAPI,
-  ExtensionContext,
-} from "@earendil-works/pi-coding-agent";
-import { type Static, Type } from "typebox";
-import { loadConfig, type AdaptiveThinkingConfig } from "./config-loader.js";
-import {
-  isThinkingLevel,
-  resolveSupportedThinkingLevels,
-  type PiThinkingLevel,
-} from "./thinking-levels.js";
-
-type NotifyType = "info" | "warning" | "error";
-
-type RuntimeState = {
-  config: AdaptiveThinkingConfig;
-  currentLevel?: PiThinkingLevel;
-  persistedLevel?: PiThinkingLevel;
-  temporaryResetLevel?: PiThinkingLevel;
-  lastToolCallWasReasoningTool?: boolean;
-  reasoningToolCallBackToBackById: Map<string, boolean>;
-};
-
-const ToolParameters = Type.Object(
-  {
-    level: Type.String({
-      minLength: 1,
-      description:
-        "The Pi thinking level to apply. Higher levels may improve hard-task quality but may take more time and resources.",
-    }),
-    persist: Type.Optional(
-      Type.Boolean({
-        default: false,
-        description:
-          "Whether to persist the setting for this session; otherwise it applies only for the current turn.",
-      }),
-    ),
-  },
-  { additionalProperties: false },
-);
-
-type ToolParameters = Static<typeof ToolParameters>;
-
-const textResult = (text: string): AgentToolResult<undefined> => ({
-  content: [{ type: "text", text }],
-  details: undefined,
-});
-
-const errorMessage = (error: unknown) => (error instanceof Error ? error.message : String(error));
-
-const agentDir = () => process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
-
-const globalSettingsPath = () => join(agentDir(), "settings.json");
-
-const sleepSync = (milliseconds: number) => {
-  const end = Date.now() + milliseconds;
-  while (Date.now() < end) {
-    // Synchronous ExtensionAPI methods require a synchronous retry loop.
-  }
-};
-
-const acquireSettingsLock = (lockPath: string) => {
-  const maxAttempts = 100;
-  const delayMs = 20;
-
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    try {
-      return lockfile.lockSync(lockPath, { realpath: false });
-    } catch (error) {
-      const code =
-        typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
-      if (code !== "ELOCKED" || attempt === maxAttempts) throw error;
-      sleepSync(delayMs);
-    }
-  }
-
-  throw new Error(`Failed to acquire settings lock: ${lockPath}`);
-};
-
-const withSettingsLock = <T>(settingsPath: string, fn: () => T): T => {
-  mkdirSync(join(settingsPath, ".."), { recursive: true });
-  const lockPath = `${settingsPath}.adaptive-thinking`;
-  if (!existsSync(lockPath)) writeFileSync(lockPath, "");
-
-  const release = acquireSettingsLock(lockPath);
-
-  try {
-    return fn();
-  } finally {
-    release();
-  }
-};
-
-const readDefaultThinkingLevel = (settingsPath: string): PiThinkingLevel | undefined => {
-  if (!existsSync(settingsPath)) return undefined;
-
-  try {
-    const parsed = JSON.parse(readFileSync(settingsPath, "utf-8")) as {
-      defaultThinkingLevel?: unknown;
-    };
-    return typeof parsed.defaultThinkingLevel === "string" &&
-      isThinkingLevel(parsed.defaultThinkingLevel)
-      ? parsed.defaultThinkingLevel
-      : undefined;
-  } catch {
-    return undefined;
-  }
-};
-
-const restoreDefaultThinkingLevel = (
-  settingsPath: string,
-  previousDefaultThinkingLevel: PiThinkingLevel | undefined,
-) => {
-  if (!existsSync(settingsPath)) return;
-
-  try {
-    const settings = JSON.parse(readFileSync(settingsPath, "utf-8")) as Record<string, unknown>;
-    if (previousDefaultThinkingLevel === undefined) {
-      delete settings.defaultThinkingLevel;
-    } else {
-      settings.defaultThinkingLevel = previousDefaultThinkingLevel;
-    }
-    writeFileSync(settingsPath, JSON.stringify(settings, undefined, 2) + "\n");
-  } catch {
-    return;
-  }
-};
-
-const withSessionOnlyThinkingLevelChange = (changeThinkingLevel: () => void) => {
-  const settingsPath = globalSettingsPath();
-
-  return withSettingsLock(settingsPath, () => {
-    const previousDefaultThinkingLevel = readDefaultThinkingLevel(settingsPath);
-
-    changeThinkingLevel();
-
-    restoreDefaultThinkingLevel(settingsPath, previousDefaultThinkingLevel);
-  });
-};
-
-const notify = (
-  ctx: ExtensionContext,
-  type: NotifyType,
-  message: string,
-  config?: Pick<AdaptiveThinkingConfig, "quiet">,
-) => {
-  if (config?.quiet) return;
-  if (!ctx.hasUI) return;
-  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;
-
-  const registerRuntimeHandlers = () => {
-    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;
-
-      if (event.toolName === state.config.toolName) {
-        state.reasoningToolCallBackToBackById.set(
-          event.toolCallId,
-          state.lastToolCallWasReasoningTool ?? false,
-        );
-        state.lastToolCallWasReasoningTool = true;
-      } else {
-        state.lastToolCallWasReasoningTool = false;
-      }
-    });
-
-    pi.on("before_agent_start", async (event, ctx) => beforeAgentStart(event, ctx));
-
-    pi.on("agent_end", async (_event, ctx) => {
-      await resetTemporaryLevel(ctx);
-      if (!runtime) return;
-      runtime.lastToolCallWasReasoningTool = false;
-      runtime.reasoningToolCallBackToBackById.clear();
-    });
-  };
-
-  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;
-    if (!state || !resetLevel) return;
-
-    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);
-    }
-  };
-
-  pi.on("session_start", async (_event, ctx) => {
-    const configResult = await loadConfig({ cwd: ctx.cwd });
-    if (!configResult.success) {
-      runtime = undefined;
-      notify(ctx, "error", configResult.error.message);
-      return;
-    }
-
-    const { config } = configResult;
-    if (!config.enabled) {
-      runtime = undefined;
-      return;
-    }
-
-    const initialLevel = pi.getThinkingLevel();
-    runtime = { config, reasoningToolCallBackToBackById: new Map() };
-    if (isThinkingLevel(initialLevel)) runtime.currentLevel = initialLevel;
-
-    pi.registerTool({
-      name: config.toolName,
-      label: "Set Thinking Level",
-      description: config.toolDescription,
-      promptSnippet: "Set the current Pi thinking level.",
-      promptGuidelines: [
-        `Use ${config.toolName} to change the thinking level when task complexity justifies a different level.`,
-      ],
-      parameters: ToolParameters,
-      execute: async (toolCallId, params: ToolParameters, _signal, _onUpdate, ctx) => {
-        const state = runtime;
-        if (!state) return textResult("Adaptive Thinking is not enabled for this session.");
-
-        const level = params.level.trim();
-        const validLevels = resolveSupportedThinkingLevels(ctx.model);
-        if (!isThinkingLevel(level) || !validLevels.includes(level)) {
-          return textResult(
-            `Invalid thinking level: ${level}. Valid levels: ${validLevels.join(", ")}.`,
-          );
-        }
-
-        const persist = params.persist ?? false;
-        const currentLevel = state.currentLevel ?? pi.getThinkingLevel();
-        if (currentLevel === level) {
-          return textResult(`Thinking level is already ${level}; no change made.`);
-        }
-
-        if (state.reasoningToolCallBackToBackById.get(toolCallId) ?? false) {
-          return textResult(
-            `Thinking level change skipped because the previous tool call was also ${state.config.toolName}. Reassess after another tool call or new user input.`,
-          );
-        }
-
-        const resetLevel =
-          state.persistedLevel ?? (isThinkingLevel(currentLevel) ? currentLevel : undefined);
-
-        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;
-        } else if (resetLevel && resetLevel !== level) {
-          state.temporaryResetLevel = resetLevel;
-        } else {
-          delete state.temporaryResetLevel;
-        }
-
-        return textResult(`Thinking level set to ${level}`);
-      },
-    });
-
-    registerRuntimeHandlers();
-  });
-}
+export { default } from "./adaptive-thinking-lifecycle.js";