pi-plus 0.1.15 → 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.

package/README.md

@@ -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>;