advisor-pi 1.0.3 → 1.2.0

package/README.md

@@ -18,21 +18,38 @@ advice to the executor.
 - Lets the executor decide when a consultation is useful.
 - Calls a configured advisor model through Pi's model registry and auth.
 - Tracks advisor uses per session branch and stops after the configured limit.
+- Caps the conversation transcript sent per call at a configurable character
+  limit (default 20000): longer transcripts keep the most recent context and
+  are marked as truncated, so per-call cost stays bounded as sessions grow.
 - Passes a prompt-cache preference (`none`, `short`, or `long`) where the
   selected provider supports it.
 - Defaults to `openai-codex/gpt-5.6-sol` with `high` thinking.
+- Validates the configured model against the registry at load: when the
+  default (or a stored/flag-provided model) does not resolve, it falls back
+  to a working model with a warning notice instead of failing every call.
+  Stored legacy defaults are only migrated when the migration target resolves.
 - Shows a compact `advisor:<provider>/<model> <thinking> <remaining>` status in Pi's
   footer when UI is available.
+- In the terminal TUI, bare `/advisor-pi` opens an interactive settings menu. It
+  edits enabled state, model, thinking, use limit, transcript cap, and cache
+  retention; it also shows the current branch use count and offers a confirmed
+  reset. Each accepted edit is validated and persisted immediately. Enter a
+  `provider/model` ID to select a model; Pi's registry validates it. The menu
+  does not list arbitrary configured model IDs, which could contain private data.
+  Use arrow keys and Enter to select, and Escape to cancel a prompt or exit the
+  menu; **Close** exits without further changes.
 
 ## Commands
 
 ```text
+/advisor-pi
 /advisor-pi status
 /advisor-pi enable
 /advisor-pi disable
 /advisor-pi model <provider>/<model>
 /advisor-pi thinking <minimal|low|medium|high|xhigh|max>
 /advisor-pi max-uses <number>
+/advisor-pi max-transcript-chars <number>
 /advisor-pi cache <none|short|long>
 /advisor-pi reset
 ```
@@ -43,15 +60,21 @@ Examples:
 /advisor-pi model openai-codex/gpt-5.6-sol
 /advisor-pi thinking high
 /advisor-pi max-uses 5
+/advisor-pi max-transcript-chars 20000
 /advisor-pi cache long
 ```
 
+Bare `/advisor-pi` keeps the text status response in print, JSON, and other
+non-TUI modes. `/advisor-pi reset` remains available as the explicit command
+for resetting this session branch's use count.
+
 ## CLI flags
 
 ```bash
 pi --advisor-model openai-codex/gpt-5.6-sol \
    --advisor-thinking high \
    --advisor-max-uses 5 \
+   --advisor-max-transcript-chars 20000 \
    --advisor-cache short
 ```
 
@@ -61,6 +84,18 @@ Disable on startup:
 pi --advisor-enabled=false
 ```
 
+## Settings persistence
+
+Deliberate `/advisor-pi` edits are stored as private, validated per-setting
+JSON files in `~/.pi/agent/advisor-pi-preferences/` (under Pi's
+`getAgentDir()`): `enabled.json`, `model.json` (provider and model ID are one
+logical setting), `thinkingLevel.json`, `maxUses.json`, `cacheRetention.json`,
+and `maxTranscriptChars.json`. The stored settings are enabled state,
+model, thinking level, max uses, cache preference, and transcript cap. Advisor
+`useCount`, branch replay state, and runtime-only request settings remain
+session-only. Explicit startup flags override the stored settings for that
+session and are not written back.
+
 ## Install
 
 Published on npm: [`advisor-pi`](https://www.npmjs.com/package/advisor-pi). Register the package with **Pi** (`pi install`) — plain `npm install` does not add it to Pi's `settings.json`.
@@ -94,7 +129,8 @@ Each advisor consultation is a separate model call. That means:
 - Advisor input and output are billed separately by the selected provider.
 - Streaming from the executor pauses while the advisor call runs.
 - Longer transcripts cost more because the advisor reads the conversation
-  context.
+  context. Each call sends at most `max-transcript-chars` characters
+  (default 20000), keeping the most recent context and marking truncation.
 - The `max-uses` setting is a safety budget; raise it only when deeper review is
   worth the extra cost.
 
@@ -117,6 +153,7 @@ specific model compatibility, and cache reads/writes may still be billed.
   reports.
 - The advisor has no tools and cannot inspect files beyond what appears in the
   transcript.
-- Very long conversations can make advisor calls slower and more expensive.
+- Very long conversations are truncated to the transcript cap before sending,
+  so older context may be omitted on advisor calls.
 - `max-uses` is tracked per Pi session branch from extension state and tool
   result details; manual session editing can affect reconstruction.

package/dist/config-ui.d.ts

@@ -0,0 +1,12 @@
+import type { AdvisorConfig } from "./index.js";
+/** Rows used by the interactive advisor-pi settings menu. */
+export type MenuRow<TKey extends string = string> = {
+    key: TKey;
+    label: string;
+};
+export type MenuKey = "enabled" | "model" | "thinking" | "max-uses" | "max-transcript-chars" | "cache" | "reset" | "close";
+/** Build the top-level settings rows, including the current value for each setting. */
+export declare function buildMenuRows(config: AdvisorConfig, useCount?: number): MenuRow<MenuKey>[];
+/** Maps a selected label back to its row; cancelled dialogs return undefined. */
+export declare function rowForLabel<TKey extends string>(rows: MenuRow<TKey>[], label: string | undefined): MenuRow<TKey> | undefined;
+//# sourceMappingURL=config-ui.d.ts.map

package/dist/config-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-ui.d.ts","sourceRoot":"","sources":["../src/config-ui.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,6DAA6D;AAC7D,MAAM,MAAM,OAAO,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,IAAI;IAAE,GAAG,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjF,MAAM,MAAM,OAAO,GAChB,SAAS,GACT,OAAO,GACP,UAAU,GACV,UAAU,GACV,sBAAsB,GACtB,OAAO,GACP,OAAO,GACP,OAAO,CAAC;AAEX,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,SAAI,GAAG,OAAO,CAAC,OAAO,CAAC,EAAE,CAiBrF;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,IAAI,SAAS,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAG5H"}

package/dist/config-ui.js

@@ -0,0 +1,26 @@
+/** Build the top-level settings rows, including the current value for each setting. */
+export function buildMenuRows(config, useCount = 0) {
+    const entries = [
+        ["enabled", "Advisor enabled", config.enabled ? "enabled" : "disabled"],
+        ["model", "Advisor model", "configured (use /advisor-pi status for ID)"],
+        ["thinking", "Advisor thinking", config.thinkingLevel],
+        ["max-uses", "Max advisor uses", String(config.maxUses)],
+        ["max-transcript-chars", "Max transcript chars", String(config.maxTranscriptChars)],
+        ["cache", "Cache retention", config.cacheRetention],
+    ];
+    const width = Math.max(...entries.map(([, label]) => label.length));
+    const rows = entries.map(([key, label, value]) => ({
+        key,
+        label: `${label.padEnd(width)}  ${value}`,
+    }));
+    rows.push({ key: "reset", label: `Reset use count  (${useCount} used)` });
+    rows.push({ key: "close", label: "Close" });
+    return rows;
+}
+/** Maps a selected label back to its row; cancelled dialogs return undefined. */
+export function rowForLabel(rows, label) {
+    if (label === undefined)
+        return undefined;
+    return rows.find((row) => row.label === label);
+}
+//# sourceMappingURL=config-ui.js.map

package/dist/config-ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-ui.js","sourceRoot":"","sources":["../src/config-ui.ts"],"names":[],"mappings":"AAeA,uFAAuF;AACvF,MAAM,UAAU,aAAa,CAAC,MAAqB,EAAE,QAAQ,GAAG,CAAC;IAChE,MAAM,OAAO,GAAqC;QACjD,CAAC,SAAS,EAAE,iBAAiB,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;QACvE,CAAC,OAAO,EAAE,eAAe,EAAE,4CAA4C,CAAC;QACxE,CAAC,UAAU,EAAE,kBAAkB,EAAE,MAAM,CAAC,aAAa,CAAC;QACtD,CAAC,UAAU,EAAE,kBAAkB,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACxD,CAAC,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACnF,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,CAAC,cAAc,CAAC;KACnD,CAAC;IACF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;QAClD,GAAG;QACH,KAAK,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,EAAE;KACzC,CAAC,CAAC,CAAC;IACJ,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,qBAAqB,QAAQ,QAAQ,EAAE,CAAC,CAAC;IAC1E,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;IAC5C,OAAO,IAAI,CAAC;AACb,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,WAAW,CAAsB,IAAqB,EAAE,KAAyB;IAChG,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;AAChD,CAAC"}

package/dist/index.d.ts

@@ -1,3 +1,55 @@
+import { type CacheRetention, type ThinkingLevel } from "@earendil-works/pi-ai";
 import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export { loadPreferences, preferencesPath, savePreferences, savePreferencesPatch } from "./preferences.js";
+export type { AdvisorPreferences, AdvisorPreferencesConfig, AdvisorPreferencesPatch } from "./preferences.js";
+export declare const STATE_ENTRY = "advisor-pi-state";
+export declare const DEFAULT_ADVISOR_MODEL = "openai-codex/gpt-5.6-sol";
+export declare const LEGACY_DEFAULT_ADVISOR_MODEL = "openai-codex/gpt-5.5";
+export declare const DEFAULT_MAX_TRANSCRIPT_CHARS = 20000;
+type AdvisorThinkingLevel = ThinkingLevel | "max";
+export type AdvisorConfig = {
+    enabled: boolean;
+    provider: string;
+    modelId: string;
+    thinkingLevel: AdvisorThinkingLevel;
+    maxUses: number;
+    cacheRetention: CacheRetention;
+    maxTokens: number;
+    timeoutMs: number;
+    maxTranscriptChars: number;
+};
+type AdvisorStateEntry = {
+    version: 1;
+    config: AdvisorConfig;
+    useCount: number;
+    updatedAt: string;
+};
+export type ModelRegistryLike = {
+    find: (provider: string, modelId: string) => unknown;
+    getAvailable?: () => Array<{
+        provider?: unknown;
+        id?: unknown;
+    }>;
+};
+export type NormalizeConfigOptions = {
+    migrateLegacyDefault?: boolean;
+};
 export default function advisorPiExtension(pi: ExtensionAPI): void;
+export declare function defaultConfig(): AdvisorConfig;
+export declare function truncateTranscript(text: string, maxChars: number): string;
+export declare function makeStateEntry(config: AdvisorConfig, useCount: number): AdvisorStateEntry;
+export declare function persistState(pi: ExtensionAPI, config: AdvisorConfig, useCount: number): void;
+export declare function normalizeConfig(input: Partial<AdvisorConfig>, fallback: AdvisorConfig, registry?: ModelRegistryLike, options?: NormalizeConfigOptions): AdvisorConfig;
+export declare function modelResolves(registry: ModelRegistryLike | undefined, provider: string, modelId: string): boolean;
+export declare function resolveAdvisorModel(registry: ModelRegistryLike | undefined, candidates: Array<{
+    provider: string;
+    modelId: string;
+}>): {
+    provider: string;
+    modelId: string;
+} | undefined;
+export declare function parseModelSpec(value: string): {
+    provider: string;
+    modelId: string;
+} | undefined;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAIN,KAAK,YAAY,EAEjB,MAAM,iCAAiC,CAAC;AAqEzC,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,EAAE,EAAE,YAAY,QAqY1D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}