pi-plus 0.1.13 → 0.1.16

package/CHANGELOG.md

@@ -10,6 +10,7 @@
 
 ### Added
 
+- The published `pi-plus` package gains a programmatic library entry alongside the `pipi` CLI: `import { createPlusAgentSession, createPlusUIContext, plusSdkExtensionFactories } from "pi-plus"` lets a host application (e.g. a desktop app) embed pi with the full pi-plus layer in-process — the compaction/context/reasoning overrides are baked into `api.js` by the same bundle-time redirect plugin as the CLI, and the seven non-TUI pi-plus extensions (subagent, tasks, memory, plan, ask-user, hooks, context-guard) are registered the same way the CLI wrapper registers them. `createPlusAgentSession()` composes the upstream `createAgentSession` with a `DefaultResourceLoader` carrying those factories, reloads it, and binds extensions once (emitting `session_start`); hosts pass dialog handlers via the `ui` option to get working `ask_user` questions (select/confirm/input bridged to native UI), or omit it for a headless session. The staged package.json now has an `exports` map (deep imports are closed off), ships a hand-authored `api.d.ts` re-exporting `@earendil-works/pi-coding-agent` types (added as an exact-pinned dependency for type resolution only; the runtime stays self-contained), and builds `api.js` as a second esbuild entry, roughly doubling the artifact size. Hosts without a pi CLI on PATH should pass `excludeTools: ["subagent"]`: the subagent tool launches a pi subprocess and could otherwise relaunch the host app itself.
 - The tab-title spinner now also runs while context compaction is in progress (manual `/compact` when idle, or automatic/overflow compaction mid-run): `session_before_compact` marks compaction active and `session_compact`/`session_compact_failed` clear it, so a backgrounded tab shows at a glance that a long compaction is running. The spinner stops only when neither the agent run nor compaction is active, so mid-run compaction (which settles the run before retrying) no longer leaves the tab static.
 - A `<tasks>` system-prompt section (registered by the `pi-plus-tasks` extension on every agent start) nudging the model to break non-trivial multi-step work into TaskCreate tasks and update statuses as it goes, and listing the session's current tasks (with status and blockers) when non-empty so resumed sessions can pick up where they left off.
 - A `<subagents>` system-prompt section (registered by the `pi-plus-subagent` extension on every agent start) nudging the model to delegate self-contained work units via the `subagent` tool — including complete, self-contained prompts and concurrent calls in one turn — and listing the agent types available in this session (built-in `worker`/`explore` plus user- and project-defined agents) with their source, tools, and model.
@@ -19,12 +20,13 @@
 - Recompaction analytics (openclaude's `RecompactionInfo`) persisted in the compaction entry's `details`: whether the compaction continues a chain, turns consumed since the previous compaction, the previous pre-compact token count, and a `willRetriggerNextTurn` prediction; set `PI_COMPACT_ANALYTICS` for a stderr diagnostic line.
 - `/settings` gains an "Auto-compact threshold" row (70%/80%/85%/90%/95%, default 80%), injected into the settings selector by the plus wrapper. The choice persists to `~/.pi/agent/pi-plus-settings.json` and applies as a percent of the effective context window, replacing the CC buffer math as the user-facing default — unlike `PI_AUTOCOMPACT_PCT_OVERRIDE`, which stays a session-scoped test knob capped at the CC buffer.
 - `/settings` gains a "Context floor" row (13000–65536 tokens, default 13000) for the floor under the effective context window: the window used for auto-compact math never drops below the output reserve plus this many tokens, even for small-context models. The choice persists to `~/.pi/agent/pi-plus-settings.json` and can only raise the built-in 13k floor (the issue-#635 guarantee stays intact); `PI_CONTEXT_FLOOR_TOKENS` overrides it for the session.
+- `/settings` gains a "Context window cap" row ("No cap"/131072/262144/524288/1048576, default "No cap") capping the context window used for auto-compact math and the footer fullness meter at min(model window, cap). The choice persists to `~/.pi/agent/pi-plus-settings.json`; `PI_AUTO_COMPACT_WINDOW` keeps its session-scoped can-only-lower semantics on top.
 
 ### Changed
 
 - The `<tasks>` system-prompt section now spells out the TaskCreate/TaskUpdate/TaskList/TaskGet signatures (parameter names, optionality, status enum, numeric-string task ids) in an "Available tools:" block after the prose nudge. Extension tools have no snippet in the `<tools>` section, so the model previously had to discover them blind — flash-tier models in particular ignored the nudge and ran multi-step work as one tool call at a time with no task tracking.
 
-- The window used for threshold math is now ceilinged at 256K tokens (`AUTOCOMPACT_MAX_WINDOW_TOKENS`) before the output reservation: models advertising windows far beyond practical agentic session sizes (e.g. the 1M-token DeepSeek V4.1 Flash) previously got an ~800K auto-compact threshold that effectively never fired, letting the transcript grow unbounded. A 1M model now triggers at ~194K (80% of the 242K effective window). `PI_AUTO_COMPACT_WINDOW` keeps its cap semantics and can only lower this further. The footer's context fullness percentage uses the same effective window as its denominator when the ceiling engages, so the meter reads "percent of the usable window" (e.g. `14.4%/242K`) instead of crawling against the unreachable 1M capacity; models at or below the ceiling are unchanged.
+- The default context window used for threshold math is no longer ceilinged at 256K (`AUTOCOMPACT_MAX_WINDOW_TOKENS` is gone): with no "Context window cap" chosen in `/settings`, the model's advertised context window is used as-is, so a 1M-context model triggers auto-compaction at 80% of its full window (~784K) and the footer meter reads against full capacity. Choosing a cap restores the old behavior (e.g. 262144 reproduces the 242K effective window and the `14.4%/242K` meter). The floor logic and `PI_AUTO_COMPACT_WINDOW`'s session-scoped lowering are unchanged.
 
 - The CC buffer math (ramped 13k–30k by effective window size, openclaude issue #1949; floored effective window for small-context models, issue #635) no longer sets the auto-compact threshold directly — it survives only as the cap for the `PI_AUTOCOMPACT_PCT_OVERRIDE` test knob. The user-facing threshold is now a percent of the effective window chosen in `/settings` (default 80%). `percentLeft` is computed against the raw context window so the displayed percentage reflects full model capacity.
 

package/README.md

@@ -6,7 +6,7 @@ All override/custom logic lives here. Direct updates to any other folder under `
 
 Ports Claude Code semantics (reference: `../free-code/`, CC v2.1.87) onto pi's context detection, compaction, and reasoning — with pi-style env var names:
 
-1. **Context usage detection** (`src/context/detection.ts`) — effective context window = `min(contextWindow, 256K) − min(maxTokens, 20000)`, so 1M-context models (e.g. DeepSeek V4.1 Flash) get a sane ~190K auto-compact threshold instead of ~800K that never fires; auto-compact threshold = a percent of the effective window (**default 80%**, adjustable 70–95% in `/settings`); warning/error = threshold ∓ 20k; blocking limit = effective window − 3k; 3-failure circuit breaker. When the 256K ceiling engages, the footer's fullness percentage is also measured against the effective window (e.g. `14.4%/242K`), so the meter tracks the usable window instead of crawling against raw 1M capacity. The "Auto-compact threshold" row persists to `~/.pi/agent/pi-plus-settings.json` (`src/context/threshold-setting.ts`); `PI_AUTOCOMPACT_PCT_OVERRIDE` keeps its session-scoped, capped-at-the-CC-buffer test semantics. The effective window is also floored at the output reserve plus a context floor buffer (**default 13k**, adjustable 13000–65536 in `/settings`); the floor only ever raises the built-in 13k minimum so small-context models keep a usable (non-negative-threshold) window, and `PI_CONTEXT_FLOOR_TOKENS` overrides it for the session.
+1. **Context usage detection** (`src/context/detection.ts`) — effective context window = `min(contextWindow, cap) − min(maxTokens, 20000)`, where the cap defaults to the model's advertised window and can be set in `/settings` ("Context window cap": "No cap"/131072/262144/524288/1048576, persisted in `~/.pi/agent/pi-plus-settings.json`). Capping below the model window gives a sane auto-compact threshold on huge-context models (e.g. the 1M-token DeepSeek V4.1 Flash capped at 262144 triggers at ~194K instead of ~800K that never fires); auto-compact threshold = a percent of the effective window (**default 80%**, adjustable 70–95% in `/settings`); warning/error = threshold ∓ 20k; blocking limit = effective window − 3k; 3-failure circuit breaker. When a cap shrinks the window, the footer's fullness percentage is also measured against the effective window (e.g. `14.4%/242K`), so the meter tracks the usable window instead of crawling against raw 1M capacity; with no cap the meter reads against full model capacity. The "Auto-compact threshold" row persists to `~/.pi/agent/pi-plus-settings.json` (`src/context/threshold-setting.ts`); `PI_AUTOCOMPACT_PCT_OVERRIDE` keeps its session-scoped, capped-at-the-CC-buffer test semantics. The effective window is also floored at the output reserve plus a context floor buffer (**default 13k**, adjustable 13000–65536 in `/settings`); the floor only ever raises the built-in 13k minimum so small-context models keep a usable (non-negative-threshold) window, and `PI_CONTEXT_FLOOR_TOKENS` overrides it for the session. `PI_AUTO_COMPACT_WINDOW` can only lower the (capped) window further for the session.
 2. **Compaction** (`src/compaction/`) — single full-conversation summary using the CC 9-section prompt (`prompt.ts`); prompt-too-long retries drop the oldest turn (`compact.ts`); post-compact re-injection of up to 5 recently read files (50k token budget). Summarization never applies the session thinking level: the summary's output cap is `0.8 × reserveTokens` and reasoning tokens count against it, so a `high` session level on a reasoning model could truncate the summary mid-generation and fail compaction ("generation hit the token cap"). Summary requests carry a no-reasoning marker (`markNoReasoning` in `src/reasoning/effort.ts`) that `wrapStreamFn` honors by stripping reasoning/thinking budgets instead of re-applying the session level.
 3. **Reasoning effort** (`src/reasoning/effort.ts`) — CC effort levels (`low`/`medium`/`high`/`max`, `max` → `xhigh` → `high` downgrading), adaptive thinking default, `ultrathink` keyword → high effort for that turn, thinking budgets from env.
 4. **Hub profiles** (`src/coding-agent/main.ts` wrapper, backed by `@earendil-works/pi-hub` = `packages/hub`) — named pi profiles (provider/models/thinking/token/base URL) stored in `~/.pi/profiles.json`, materialized into isolated agent dirs under `~/.pi/pi-hub/profiles/<name>/`. Adds `pipi profile …`, `pipi use` / `pipi unuse`, and the `pipi --as <name>` flag. The wrapper resolves the profile, sets `PI_CODING_AGENT_DIR` in-process (read lazily by `getAgentDir()`), and delegates to the original `main`.
@@ -46,7 +46,7 @@ source <(pipi completion bash)   # add to ~/.bashrc
 | Var                           | Values                              | Effect                                                          |
 | ----------------------------- | ----------------------------------- | --------------------------------------------------------------- |
 | `PI_MAX_CONTEXT_TOKENS`       | number                              | Overrides `model.contextWindow` after model resolution          |
-| `PI_AUTO_COMPACT_WINDOW`      | number                              | Caps the window used for threshold math (cannot raise the 256K ceiling) |
+| `PI_AUTO_COMPACT_WINDOW`      | number                              | Session cap on the threshold-math window (lowers the persisted cap) |
 | `PI_AUTOCOMPACT_PCT_OVERRIDE` | 1–100                               | Auto-compact threshold as % of effective window (capped at default) |
 | `PI_CONTEXT_FLOOR_TOKENS`     | number ≥ 13000                      | Context floor override (only raises the built-in 13k floor)     |
 | `PI_BLOCKING_LIMIT_OVERRIDE`  | number                              | Blocking limit override                                         |
@@ -88,14 +88,56 @@ npm publish --access public --ignore-scripts   # in packages/plus/dist/npm
 
 The bundle applies `loader/redirects.mjs` at bundle time (esbuild plugin) and keeps each
 module a singleton by funneling every `packages/*/src/**` import with a compiled `dist/`
-counterpart to that dist file. `--no-env` is preserved via a banner scrub. Provider
-credentials, config dir (`~/.pi`), and session layout are identical to source-mode `pipi`.
+counterpart to that dist file. `--no-env` is preserved via a banner scrub (inert for
+library imports: it only scrubs when `process.argv` contains a literal `--no-env`).
+Provider credentials, config dir (`~/.pi`), and session layout are identical to
+source-mode `pipi`.
+
+### Programmatic API (library hosts)
+
+The same package also exposes a programmatic entry for hosts that embed pi-plus
+in-process (e.g. a desktop app) instead of running the `pipi` CLI:
+
+```js
+import { createPlusAgentSession } from "pi-plus";
+
+const { session } = await createPlusAgentSession({
+	cwd: projectDir,
+	ui: {
+		select: async (title, options) => showPicker(title, options),
+		confirm: async (title, message) => showConfirm(title, message),
+		input: async (title, placeholder) => showInput(title, placeholder),
+	},
+	// Hosts without a pi CLI on PATH should exclude the subagent tool: it
+	// launches a pi subprocess and could otherwise relaunch the host app.
+	excludeTools: ["subagent"],
+});
+await session.prompt("Review this repository");
+```
+
+- The full pi-plus layer is included: the compaction/context/reasoning overrides are
+  baked into `api.js` by the same bundle-time redirect plugin as the CLI, and the seven
+  non-TUI pi-plus extensions (subagent, tasks, memory, plan, ask-user, hooks,
+  context-guard) are registered exactly as the CLI wrapper registers them.
+- `createPlusAgentSession()` extends the upstream `createAgentSession` (re-exported, with
+  the whole upstream SDK surface) with those extension factories, and always binds
+  extensions once — do not call `session.bindExtensions()` yourself. Pass `ui` dialog
+  handlers to get working `ask_user` questions (bound with mode `"rpc"`, so the tool
+  falls back to sequential select/input/confirm dialogs bridged to your UI); omit `ui`
+  for a headless session.
+- The staged `package.json` has an `exports` map, so deep imports (e.g.
+  `pi-plus/pipi.js`) are no longer reachable; `api.d.ts` re-exports the
+  `@earendil-works/pi-coding-agent` types (exact-pinned dependency, type resolution
+  only — the runtime is self-contained). Building `api.js` as a second esbuild entry
+  roughly doubles the artifact size.
 
 Known limitations of the compiled artifact:
 
 - `pipi server` / `pipi client` experimental subcommands (`PI_EXPERIMENTAL=1`) spawn sibling JS
   files that are not emitted next to the bundle; use source-mode `./pipi` for those.
 - `docs/` and `examples/` are not shipped, so `/docs`-style paths into them are absent.
+- Hub profile resolution (`pipi --as <name>`, `pipi profile …`) is CLI-launch logic and is
+  not part of the programmatic entry; SDK hosts pass `cwd`/`agentDir` explicitly.
 
 ## Tests
 

package/api.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Public type contract for the "pi-plus" npm package's programmatic entry
+ * (api.js). Hand-authored mirror of src/api.ts: the runtime is fully
+ * self-contained in api.js (built from this repo with the pi-plus override
+ * layer baked in), so this file only needs to re-export the upstream SDK
+ * types and declare the pi-plus additions. A vitest drift guard
+ * (test/api.test.ts) asserts every runtime export of src/api.ts appears here.
+ */
+
+export * from "@earendil-works/pi-coding-agent";
+
+import type {
+	CreateAgentSessionOptions,
+	CreateAgentSessionResult,
+	ExtensionCommandContextActions,
+	ExtensionError,
+	ExtensionUIContext,
+	InlineExtension,
+} from "@earendil-works/pi-coding-agent";
+
+export declare const plusSdkExtensionFactories: InlineExtension[];
+
+export interface PlusUIDialogHandlers {
+	select(title: string, options: string[]): Promise<string | undefined>;
+	confirm(title: string, message: string): Promise<boolean>;
+	input(title: string, placeholder?: string): Promise<string | undefined>;
+	editor?(title: string, prefill?: string): Promise<string | undefined>;
+	notify?(message: string, type?: "info" | "warning" | "error"): void;
+}
+
+export declare function createPlusUIContext(handlers: PlusUIDialogHandlers): ExtensionUIContext;
+
+export interface CreatePlusAgentSessionOptions extends CreateAgentSessionOptions {
+	extensionFactories?: InlineExtension[];
+	ui?: PlusUIDialogHandlers;
+	commandContextActions?: ExtensionCommandContextActions;
+	abortHandler?: () => void;
+	shutdownHandler?: () => void;
+	onError?: (error: ExtensionError) => void;
+}
+
+export declare function createPlusAgentSession(
+	options?: CreatePlusAgentSessionOptions,
+): Promise<CreateAgentSessionResult>;