pi-plus-sdk 0.0.0-stage → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- 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 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

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# plus-api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Builds the **`pi-plus-sdk`** npm package: pi with the pi-plus override layer as an
+embeddable library, for hosts that run pi in-process (e.g. a desktop app) instead of
+running the `pipi` CLI. The CLI counterpart is [`../plus-cli`](../plus-cli) (the
+`pi-plus` package); the shared override core is [`../plus`](../plus).
+
+## Usage
+
+```js
+import { createPlusAgentSession } from "pi-plus-sdk";
+
+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 shared bundle-time redirect plugin, and the nine
+  non-TUI pi-plus extensions (subagent, tasks, memory, plan, ask-user, hooks,
+  context-guard, `/cd`, `/init`) are registered exactly as the CLI wrapper registers them. No CLI
+  logic ships in this artifact: no hub dispatch, no completion, no pipi help text,
+  no banner/vim/tab-title/plain-tools.
+- `createPlusAgentSession()` extends the upstream `createAgentSession` (re-exported,
+  with the whole upstream SDK surface) 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 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).
+- `main` is re-exported from the upstream barrel but redirects to a stub that throws:
+  the CLI entry is not part of the SDK. Likewise `parseArgs`/`Args` and
+  `SettingsSelectorComponent` are upstream pi's versions, not the pipi-branded CLI
+  wrappers.
+
+## Building the artifact
+
+```bash
+npm run build:offline          # at the repo root, first
+npm run build                  # in packages/plus-api
+npm publish --access public --ignore-scripts   # in packages/plus-api/dist/npm
+```
+
+## Tests
+
+```bash
+npx vitest run   # from packages/plus-api
+```

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