pi-plus-sdk 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -4,6 +4,11 @@
 
 ### Added
 
+- Runtime settings layering for hub profiles applies to SDK hosts with no environment plumbing (shared `loader/redirects.mjs` entry for `coding-agent/src/core/settings-manager.ts`): whenever the agent dir passed to `SettingsManager.create` is a hub-materialized profile dir (a direct child of `~/.pi/pi-hub/profiles`, honoring `PI_HUB_PI_DIR`/`PI_HUB_DIR`; the pipi-set `PI_PLUS_BASE_AGENT_DIR` marker also still activates it), the global scope reads the base agent `settings.json` deep-merged under the profile `settings.json` with the profile winning, and writes route per top-level key — `defaultProvider`/`defaultModel` to the profile file, everything else to the agent file with any profile shadow cleared. Any other agent dir keeps `SettingsManager.create` behaving exactly as upstream.
+- The pi-plus context settings are re-exported from the SDK surface (`packages/plus/src/context/threshold-setting.ts`): `readPlusSettings/writePlusSettings/getPlusSettingsPath` for the pi-plus settings store next to `settings.json`, plus the typed getters/setters and UI formatters behind the pipi `/settings` rows — `get/setAutoCompactThresholdPercent` (default 80%), `get/setContextFloorTokens` (default/built-in minimum 13000), and `get/setContextWindowCapTokens` (undefined = no cap). Embedding hosts get the same knobs the TUI edits, against the same file detection actually reads. `SessionManager.deleteSession` and `SessionManager.search` (new in the re-exported upstream surface) cover transcript deletion and title/content search for history-management UIs.
 - Initial **`pi-plus-sdk`** npm artifact (published from this package): the programmatic pi-plus entry, split out of the `pi-plus` package so library hosts embed pi in-process with zero CLI logic. `import { createPlusAgentSession, createPlusUIContext, plusSdkExtensionFactories } from "pi-plus-sdk"` gives a host application (e.g. a desktop app) the compaction/context/reasoning overrides (baked in at bundle time by the shared redirect plugin) plus the nine non-TUI pi-plus extensions (subagent, tasks, memory, plan, ask-user, hooks, context-guard, /cd, /init). `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 has an `exports` map (deep imports 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 has no bin. 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 `/init` extension (shared core, `packages/plus/src/extensions/init/`) is registered by `plusSdkExtensionFactories` too: the `/init` command creates or improves `PI.md` at the cwd root and `PI.md` is auto-loaded into every agent run via the system prompt's context files.
+- The `/init` extension (shared core, `packages/plus/src/extensions/init/`) is registered by `plusSdkExtensionFactories` too: the `/init` command creates or improves `AGENTS.md` at the cwd root — pi's default project instructions file, loaded automatically by upstream's context loader.
+- `createPlusAgentSessionRuntime(options?)` — a runtime-backed sibling of `createPlusAgentSession` for embedding hosts that need the CLI's session-replacement machinery. It composes `createAgentSessionServices`/`createAgentSessionFromServices`/`createAgentSessionRuntime` (the same layering the CLI's main uses, trimmed to host concerns) with the pi-plus extension factories and binding rules: extensions are bound exactly once per session through the rebind hook (initial bind plus every `switchSession`/`fork`/`newSession` replacement, emitting one `session_start` each with the matching reason), and the default `commandContextActions` route `waitForIdle`/`newSession`/`fork`/`navigateTree`/`switchSession`/`reload` to the runtime + live session, which is what makes `/cd` (and `/clone`-style `runtime.fork(leafId, { position: "at" })`) work in-process. The live session is `runtime.session` — hosts read it after each replacement or subscribe in the new `onRebind` callback; the initial session defaults to `SessionManager.create(cwd, getDefaultSessionDir(cwd, agentDir))`, and `projectTrusted` (default true) plus `resourceLoaderOptions` passthroughs cover per-cwd settings and loader customization. The coding-agent barrel additionally exports `getDefaultSessionDir` (plus the `DefaultResourceLoaderOptions` type) to support this entry.
+- `addProfileModel(name, model)` and `removeProfileModel(name, model)` join the curated profile surface (implemented in `@earendil-works/pi-hub`): append a model without selecting it (bounded by the same three-models-per-profile limit) and remove one with the `pipi` CLI delete semantics — the default promotes to the next remaining model, and removing the last clears `models`/`model` so the profile inherits. Both return a human-readable message for host UIs, completing the per-profile model editing that `setProfileDefaultModel` started.
+- `setProfileDefaultModel(name, model)` joins the curated profile surface (implemented in `@earendil-works/pi-hub`): selects a profile's default model — the list position 1 that materialization writes as `settings.defaultModel` — moving an existing model or adding a new one (bounded by the same three-models-per-profile limit the `pipi` CLI enforces), and returns a human-readable message for host UIs. This is the library entry for the "select model" behavior that previously lived only in the CLI command layer.
 - The SDK build redirects the upstream `main.ts` to a stub that throws — the CLI entry graph (startup UI, session picker, auth command, …) stays out of `api.js`, and calling `main()` is a clear error instead of silently running un-layered upstream pi. The re-exported `parseArgs`/`SettingsSelectorComponent` resolve to upstream pi (no pipi help text or CLI settings rows leak into the library surface).

package/README.md

@@ -32,11 +32,21 @@ await session.prompt("Review this repository");
   completion, no pipi help text, no banner/vim/tab-title/plain-tools.
 - Profile management ships as a library: the curated `@earendil-works/pi-hub`
   surface is re-exported (`src/profiles.ts`) — `loadProfiles/findProfile/
-  addProfile/updateProfile/removeProfile/renameProfile/setDefaultProfile/
-  clearDefaultProfile/getDefaultProfileName` for `~/.pi/profiles.json`, and
+  addProfile/addProfileModel/updateProfile/removeProfile/removeProfileModel/
+  renameProfile/setDefaultProfile/clearDefaultProfile/getDefaultProfileName/
+  setProfileDefaultModel` for
+  `~/.pi/profiles.json`, and
   `materializeProfile/removeProfileDir/profileDirFor/AGENT_DIR/
   syncProfilePackagesToSource` for the per-profile agent dirs. Hosts get the
   exact contract the `pipi` CLI dispatches instead of reimplementing it.
+- The pi-plus context settings ship as a library: `readPlusSettings/writePlusSettings`
+  and the `get/setAutoCompactThresholdPercent`, `get/setContextFloorTokens`,
+  `get/setContextWindowCapTokens` helpers (plus formatters/parsers) manage the
+  pi-plus settings store (`<agentDir>/pi-plus-settings.json`) that drives
+  auto-compaction trigger math — the same file the pipi TUI `/settings` rows edit.
+  Session history management completes the surface: `SessionManager.listAll` to
+  enumerate, `SessionManager.search(query)` to match titles and transcript text, and
+  `SessionManager.deleteSession(path)` to remove a transcript.
 - Provider login ships as a library (`src/auth.ts`): `loginProvider(providerId, { agentDir?, interaction?, signal?, method? })`
   runs pi's model-runtime login flow (OAuth login page / API-key setup — the same
   flow `pipi profile add <name> -p <provider>` triggers) and persists the credential
@@ -50,6 +60,21 @@ await session.prompt("Review this repository");
   `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.
+- `createPlusAgentSessionRuntime()` returns an `AgentSessionRuntime` instead of a
+  single session: the same pi-plus layer and one-bind-per-session rules, plus the
+  CLI's session-replacement machinery — `runtime.cd`-style switches
+  (`switchSession`), `newSession`, and `fork` (with `{position: "at"}` for the CLI's
+  in-place `/clone`). The pi-plus `/cd`/`/init` extensions and anything else needing
+  `commandContextActions` work out of the box: the factory wires runtime-routed
+  actions by default (override via the `commandContextActions` option). The live
+  session is `runtime.session` and **changes on every replacement** — re-subscribe in
+  the `onRebind` callback (it also fires for the initial bind) and never call
+  `bindExtensions()` yourself. `runtime.dispose()` is async and emits
+  `session_shutdown`.
+- `session.setAutoCompactionEnabled(bool)` writes the **global**
+  `<agentDir>/settings.json` compaction flag (not a per-session setting), so a host
+  toggle labeled per-session would surprise users — it also flips behavior for the
+  `pipi` CLI sharing that agent dir.
 - The staged `package.json` has an `exports` map, so deep imports are not reachable;
   `api.d.ts` re-exports the `@earendil-works/pi-coding-agent` types (exact-pinned
   dependency, type resolution only — the runtime is self-contained).

package/anthropic.js

@@ -0,0 +1,74 @@
+var __require=(x=>typeof require<"u"?require:typeof Proxy<"u"?new Proxy(x,{get:(a,b)=>(typeof require<"u"?require:a)[b]}):x)(function(x){if(typeof require<"u")return require.apply(this,arguments);throw Error('Dynamic require of "'+x+'" is not supported')});var procEnvCache=null;function getBunSandboxEnvValue(name){if(!(typeof process>"u"||!process.versions?.bun||Object.keys(process.env).length>0)){if(procEnvCache===null){procEnvCache=new Map;try{let{readFileSync}=__require("node:fs"),data=readFileSync("/proc/self/environ","utf-8");for(let entry of data.split("\0")){let idx=entry.indexOf("=");idx>0&&procEnvCache.set(entry.slice(0,idx),entry.slice(idx+1))}}catch{}}return procEnvCache.get(name)}}function getProviderEnvValue(name,env){return env?.[name]||(typeof process<"u"?process.env[name]:void 0)||getBunSandboxEnvValue(name)||void 0}var LOGO_SVG='<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 800" aria-hidden="true"><path fill="#fff" fill-rule="evenodd" d="M165.29 165.29 H517.36 V400 H400 V517.36 H282.65 V634.72 H165.29 Z M282.65 282.65 V400 H400 V282.65 Z"/><path fill="#fff" d="M517.36 400 H634.72 V634.72 H517.36 Z"/></svg>';function escapeHtml(value){return value.replaceAll("&","&amp;").replaceAll("<","&lt;").replaceAll(">","&gt;").replaceAll('"',"&quot;").replaceAll("'","&#39;")}function renderPage(options){let title=escapeHtml(options.title),heading=escapeHtml(options.heading),message=escapeHtml(options.message),details=options.details?escapeHtml(options.details):void 0;return`<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${title}</title>
+  <style>
+    :root {
+      --text: #fafafa;
+      --text-dim: #a1a1aa;
+      --page-bg: #09090b;
+      --font-sans: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+      --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+    }
+    * { box-sizing: border-box; }
+    html { color-scheme: dark; }
+    body {
+      margin: 0;
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 24px;
+      background: var(--page-bg);
+      color: var(--text);
+      font-family: var(--font-sans);
+      text-align: center;
+    }
+    main {
+      width: 100%;
+      max-width: 560px;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+    }
+    .logo {
+      width: 72px;
+      height: 72px;
+      display: block;
+      margin-bottom: 24px;
+    }
+    h1 {
+      margin: 0 0 10px;
+      font-size: 28px;
+      line-height: 1.15;
+      font-weight: 650;
+      color: var(--text);
+    }
+    p {
+      margin: 0;
+      line-height: 1.7;
+      color: var(--text-dim);
+      font-size: 15px;
+    }
+    .details {
+      margin-top: 16px;
+      font-family: var(--font-mono);
+      font-size: 13px;
+      color: var(--text-dim);
+      white-space: pre-wrap;
+      word-break: break-word;
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <div class="logo">${LOGO_SVG}</div>
+    <h1>${heading}</h1>
+    <p>${message}</p>
+    ${details?`<div class="details">${details}</div>`:""}
+  </main>
+</body>
+</html>`}function oauthSuccessHtml(message){return renderPage({title:"Authentication successful",heading:"Authentication successful",message})}function oauthErrorHtml(message,details){return renderPage({title:"Authentication failed",heading:"Authentication failed",message,details})}function base64urlEncode(bytes){let binary="";for(let byte of bytes)binary+=String.fromCharCode(byte);return btoa(binary).replace(/\+/g,"-").replace(/\//g,"_").replace(/=/g,"")}async function generatePKCE(){let verifierBytes=new Uint8Array(32);crypto.getRandomValues(verifierBytes);let verifier=base64urlEncode(verifierBytes),data=new TextEncoder().encode(verifier),hashBuffer=await crypto.subtle.digest("SHA-256",data),challenge=base64urlEncode(new Uint8Array(hashBuffer));return{verifier,challenge}}var nodeApis=null,nodeApisPromise=null,decode=s=>atob(s),CLIENT_ID=decode("OWQxYzI1MGEtZTYxYi00NGQ5LTg4ZWQtNTk0NGQxOTYyZjVl"),AUTHORIZE_URL="https://claude.ai/oauth/authorize",TOKEN_URL="https://platform.claude.com/v1/oauth/token",CALLBACK_HOST=getProviderEnvValue("PI_OAUTH_CALLBACK_HOST")||"127.0.0.1",CALLBACK_PORT=53692,CALLBACK_PATH="/callback",REDIRECT_URI=`http://localhost:${CALLBACK_PORT}${CALLBACK_PATH}`,SCOPES="org:create_api_key user:profile user:inference user:sessions:claude_code user:mcp_servers user:file_upload";async function getNodeApis(){if(nodeApis)return nodeApis;if(!nodeApisPromise){if(typeof process>"u"||!process.versions?.node&&!process.versions?.bun)throw new Error("Anthropic OAuth is only available in Node.js environments");nodeApisPromise=import("node:http").then(httpModule=>({createServer:httpModule.createServer}))}return nodeApis=await nodeApisPromise,nodeApis}function parseAuthorizationInput(input){let value=input.trim();if(!value)return{};try{let url=new URL(value);return{code:url.searchParams.get("code")??void 0,state:url.searchParams.get("state")??void 0}}catch{}if(value.includes("#")){let[code,state]=value.split("#",2);return{code,state}}if(value.includes("code=")){let params=new URLSearchParams(value);return{code:params.get("code")??void 0,state:params.get("state")??void 0}}return{code:value}}function formatErrorDetails(error){if(error instanceof Error){let details=[`${error.name}: ${error.message}`],errorWithCode=error;return errorWithCode.code&&details.push(`code=${errorWithCode.code}`),typeof errorWithCode.errno<"u"&&details.push(`errno=${String(errorWithCode.errno)}`),typeof error.cause<"u"&&details.push(`cause=${formatErrorDetails(error.cause)}`),error.stack&&details.push(`stack=${error.stack}`),details.join("; ")}return String(error)}async function startCallbackServer(expectedState){let{createServer}=await getNodeApis();return new Promise((resolve,reject)=>{let settleWait,waitForCodePromise=new Promise(resolveWait=>{let settled=!1;settleWait=value=>{settled||(settled=!0,resolveWait(value))}}),server=createServer((req,res)=>{try{let url=new URL(req.url||"","http://localhost");if(url.pathname!==CALLBACK_PATH){res.writeHead(404,{"Content-Type":"text/html; charset=utf-8"}),res.end(oauthErrorHtml("Callback route not found."));return}let code=url.searchParams.get("code"),state=url.searchParams.get("state"),error=url.searchParams.get("error");if(error){res.writeHead(400,{"Content-Type":"text/html; charset=utf-8"}),res.end(oauthErrorHtml("Anthropic authentication did not complete.",`Error: ${error}`));return}if(!code||!state){res.writeHead(400,{"Content-Type":"text/html; charset=utf-8"}),res.end(oauthErrorHtml("Missing code or state parameter."));return}if(state!==expectedState){res.writeHead(400,{"Content-Type":"text/html; charset=utf-8"}),res.end(oauthErrorHtml("State mismatch."));return}res.writeHead(200,{"Content-Type":"text/html; charset=utf-8"}),res.end(oauthSuccessHtml("Anthropic authentication completed. You can close this window.")),settleWait?.({code,state})}catch{res.writeHead(500,{"Content-Type":"text/plain; charset=utf-8"}),res.end("Internal error")}});server.on("error",err=>{reject(err)}),server.listen(CALLBACK_PORT,CALLBACK_HOST,()=>{resolve({server,redirectUri:REDIRECT_URI,cancelWait:()=>{settleWait?.(null)},waitForCode:()=>waitForCodePromise})})})}async function postJson(url,body,signal){let response=await fetch(url,{method:"POST",headers:{"Content-Type":"application/json",Accept:"application/json"},body:JSON.stringify(body),signal:AbortSignal.any([signal,AbortSignal.timeout(3e4)])}),responseBody=await response.text();if(!response.ok)throw new Error(`HTTP request failed. status=${response.status}; url=${url}; body=${responseBody}`);return responseBody}async function exchangeAuthorizationCode(code,state,verifier,redirectUri,signal){let responseBody;try{responseBody=await postJson(TOKEN_URL,{grant_type:"authorization_code",client_id:CLIENT_ID,code,state,redirect_uri:redirectUri,code_verifier:verifier},signal)}catch(error){throw new Error(`Token exchange request failed. url=${TOKEN_URL}; redirect_uri=${redirectUri}; response_type=authorization_code; details=${formatErrorDetails(error)}`)}let tokenData;try{tokenData=JSON.parse(responseBody)}catch(error){throw new Error(`Token exchange returned invalid JSON. url=${TOKEN_URL}; body=${responseBody}; details=${formatErrorDetails(error)}`)}return{type:"oauth",refresh:tokenData.refresh_token,access:tokenData.access_token,expires:Date.now()+tokenData.expires_in*1e3-300*1e3}}async function loginAnthropic(interaction){let{verifier,challenge}=await generatePKCE(),server=await startCallbackServer(verifier),manualAbort=new AbortController,onAbort=()=>server.cancelWait();interaction.signal.addEventListener("abort",onAbort,{once:!0}),interaction.signal.aborted&&onAbort();let code,state,manualInput,manualError;try{let authParams=new URLSearchParams({code:"true",client_id:CLIENT_ID,response_type:"code",redirect_uri:REDIRECT_URI,scope:SCOPES,code_challenge:challenge,code_challenge_method:"S256",state:verifier});interaction.notify({type:"auth_url",url:`${AUTHORIZE_URL}?${authParams.toString()}`,instructions:"Complete login in your browser. If the browser is on another machine, paste the final redirect URL here."});let manualPromise=interaction.prompt({type:"manual_code",message:"Complete login in your browser, or paste the authorization code / redirect URL here:",placeholder:REDIRECT_URI,signal:manualAbort.signal}).then(input=>{manualInput=input,server.cancelWait()}).catch(error=>{manualError=error instanceof Error?error:new Error(String(error)),server.cancelWait()}),result=await server.waitForCode();if(manualError)throw manualError;if(result?.code)code=result.code,state=result.state;else if(manualInput){let parsed=parseAuthorizationInput(manualInput);if(parsed.state&&parsed.state!==verifier)throw new Error("OAuth state mismatch");code=parsed.code,state=parsed.state??verifier}if(!code){if(await manualPromise,manualError)throw manualError;if(manualInput){let parsed=parseAuthorizationInput(manualInput);if(parsed.state&&parsed.state!==verifier)throw new Error("OAuth state mismatch");code=parsed.code,state=parsed.state??verifier}}if(!code)throw new Error("Missing authorization code");if(!state)throw new Error("Missing OAuth state");return interaction.notify({type:"progress",message:"Exchanging authorization code for tokens..."}),exchangeAuthorizationCode(code,state,verifier,REDIRECT_URI,interaction.signal)}finally{interaction.signal.removeEventListener("abort",onAbort),manualAbort.abort(),server.server.close()}}async function refreshAnthropicToken(refreshToken,signal){let responseBody;try{responseBody=await postJson(TOKEN_URL,{grant_type:"refresh_token",client_id:CLIENT_ID,refresh_token:refreshToken},signal)}catch(error){throw new Error(`Anthropic token refresh request failed. url=${TOKEN_URL}; details=${formatErrorDetails(error)}`)}let data;try{data=JSON.parse(responseBody)}catch(error){throw new Error(`Anthropic token refresh returned invalid JSON. url=${TOKEN_URL}; body=${responseBody}; details=${formatErrorDetails(error)}`)}return{type:"oauth",refresh:data.refresh_token,access:data.access_token,expires:Date.now()+data.expires_in*1e3-300*1e3}}var anthropicOAuth={name:"Anthropic (Claude Pro/Max)",isSubscription:!0,login:loginAnthropic,refresh:(credential,signal)=>refreshAnthropicToken(credential.refresh,signal),async toAuth(credential){return{apiKey:credential.access}}};export{anthropicOAuth};

package/api.d.ts

@@ -10,8 +10,11 @@
 export * from "@earendil-works/pi-coding-agent";
 
 import type {
+	AgentSession,
+	AgentSessionRuntime,
 	CreateAgentSessionOptions,
 	CreateAgentSessionResult,
+	DefaultResourceLoaderOptions,
 	ExtensionCommandContextActions,
 	ExtensionError,
 	ExtensionUIContext,
@@ -43,6 +46,38 @@ export declare function createPlusAgentSession(
 	options?: CreatePlusAgentSessionOptions,
 ): Promise<CreateAgentSessionResult>;
 
+export interface CreatePlusAgentSessionRuntimeOptions extends CreateAgentSessionOptions {
+	extensionFactories?: InlineExtension[];
+	ui?: PlusUIDialogHandlers;
+	/** Overrides the runtime-routed actions (switchSession/fork/newSession/...)
+	 *  the factory wires by default, same shape as bindExtensions' binding. */
+	commandContextActions?: ExtensionCommandContextActions;
+	abortHandler?: () => void;
+	shutdownHandler?: () => void;
+	onError?: (error: ExtensionError) => void;
+	/** Called after every extension bind: the initial session and each session
+	 *  replacement. Re-subscribe to the new session here; the previous
+	 *  AgentSession object is disposed after a replacement. */
+	onRebind?: (session: AgentSession) => void | Promise<void>;
+	/** Project-trust flag for per-cwd SettingsManagers (default true). */
+	projectTrusted?: boolean;
+	/** Loader passthroughs (additionalSkillPaths, noSkills, systemPrompt, ...)
+	 *  applied on every recreation; cwd/agentDir/settingsManager/extensionFactories are owned by the factory. */
+	resourceLoaderOptions?: Omit<
+		DefaultResourceLoaderOptions,
+		"cwd" | "agentDir" | "settingsManager" | "extensionFactories"
+	>;
+}
+
+/** Runtime-backed createPlusAgentSession: same pi-plus layer and binding rules,
+ *  but returns an AgentSessionRuntime with CLI-level session replacement
+ *  (/cd, newSession, fork/clone, switchSession). The live session is
+ *  `runtime.session` — it changes on every replacement; hosts must NOT call
+ *  bindExtensions themselves. */
+export declare function createPlusAgentSessionRuntime(
+	options?: CreatePlusAgentSessionRuntimeOptions,
+): Promise<AgentSessionRuntime>;
+
 /**
  * Profile management: the curated @earendil-works/pi-hub surface bundled into
  * api.js (profiles.json CRUD + per-profile materialized agent dirs). Types are
@@ -84,9 +119,21 @@ export declare function findProfile(name: string): Profile | undefined;
 export declare function getDefaultProfileName(): string | undefined;
 export declare function setDefaultProfile(name: string): void;
 export declare function clearDefaultProfile(): void;
+/** Select a profile's default model (list position 1, materialized as
+ *  settings.defaultModel); adds it when absent. Throws for an unknown profile,
+ *  an empty model, or a new model beyond the 3-per-profile bound. */
+export declare function setProfileDefaultModel(name: string, model: string): string;
 export declare function addProfile(name: string, profile: Profile): void;
+/** Append a model to a profile without selecting it; becomes the default when
+ *  the profile had no model. Throws for an unknown profile, a duplicate or
+ *  empty model, or a fourth model. */
+export declare function addProfileModel(name: string, model: string): string;
 export declare function updateProfile(name: string, profile: Profile): void;
 export declare function removeProfile(name: string): void;
+/** Remove a model from a profile; the default promotes to the next remaining
+ *  model, and removing the last clears both `models` and `model`. A model not
+ *  in the list is a no-op with a message; throws for an unknown profile. */
+export declare function removeProfileModel(name: string, model: string): string;
 export declare function renameProfile(oldName: string, newName: string): void;
 export declare function profileDirFor(name: string): string;
 export declare function materializeProfile(name: string, profile: Profile): string;
@@ -164,3 +211,53 @@ export declare function loginProvider(providerId: string, options?: LoginProvide
 
 /** Readline-based AuthInteraction for terminal use (prompts on stdin, auth URLs opened in the browser). */
 export declare function createTerminalAuthInteraction(): AuthInteraction;
+
+// ---------------------------------------------------------------------------
+// pi-plus settings store (~/.pi/agent/pi-plus-settings.json): auto-compaction
+// threshold percent, context floor buffer and context window cap. Re-exported
+// from packages/plus/src/context/threshold-setting.ts; the runtime bundle
+// inlines the module. Pass an explicit `path` to read/write a specific agent
+// dir's copy; the default follows the process agent dir (PI_AGENT_DIR).
+// ---------------------------------------------------------------------------
+
+/** Env var that overrides the settings file path (tests, debugging). */
+export declare const PLUS_SETTINGS_ENV: "PI_PLUS_SETTINGS_FILE";
+
+export interface PlusSettings {
+	/** Percent (1-100) of the effective context window at which auto-compaction triggers. */
+	autoCompactThresholdPercent?: number;
+	/** Minimum floor buffer (tokens) for the effective context window (>= 13000). */
+	contextFloorTokens?: number;
+	/** Cap (tokens >= 32768) on the context window used for auto-compact math. */
+	contextWindowCapTokens?: number;
+}
+
+export declare function getPlusSettingsPath(): string;
+/** Read the store; missing or malformed files yield {} (never throws). */
+export declare function readPlusSettings(path?: string): PlusSettings;
+/** Persist the store, replacing only the fields present in `patch`; a field
+ *  explicitly set to undefined deletes that key, absent fields are untouched. */
+export declare function writePlusSettings(patch: PlusSettings, path?: string): void;
+
+/** Default threshold: 80% of the effective context window. */
+export declare const DEFAULT_AUTO_COMPACT_THRESHOLD_PERCENT: number;
+export declare function getAutoCompactThresholdPercent(): number;
+/** Persist a choice; undefined resets to the default (deletes the key). */
+export declare function setAutoCompactThresholdPercent(percent: number | undefined): void;
+export declare function formatAutoCompactThresholdPercent(percent: number): string;
+export declare function parseAutoCompactThresholdChoice(choice: string): number;
+
+/** Default/built-in minimum context floor buffer. */
+export declare const DEFAULT_CONTEXT_FLOOR_TOKENS: number;
+export declare const MIN_CONTEXT_FLOOR_TOKENS: number;
+export declare function getContextFloorTokens(): number;
+export declare function setContextFloorTokens(tokens: number | undefined): void;
+export declare function formatContextFloorTokens(tokens: number): string;
+export declare function parseContextFloorChoice(choice: string): number;
+
+/** Lowest accepted context window cap; undefined means no cap. */
+export declare const MIN_CONTEXT_WINDOW_CAP_TOKENS: number;
+export declare function getContextWindowCapTokens(): number | undefined;
+export declare function setContextWindowCapTokens(tokens: number | undefined): void;
+export declare function formatContextWindowCapTokens(tokens: number | undefined): string;
+export declare function parseContextWindowCapChoice(choice: string): number | undefined;