@selesai/code 0.3.0 → 0.3.2

package/docs/shared-host-extensions.md

@@ -0,0 +1,109 @@
+# Shared Host Extensions
+
+Selesai is a pi fork with its own config directory (`~/.selesai/agent/`). By default it only reads your extensions from there. If you already use `pi` and have extensions installed under `~/.pi/agent/extensions/`, you can let selesai reuse them without duplicating auth, sessions, models, or settings.
+
+This page covers three things:
+
+1. The shared-host fallback (how selesai reads pi's extensions).
+2. Collisions: what happens when the same extension exists in both.
+3. Picking the winner per extension via `extensionHost`.
+
+## What gets shared, and what does not
+
+| Read from `~/.pi/agent/` | Kept separate under `~/.selesai/agent/` |
+|---|---|
+| `extensions/` | `auth.json` |
+| | `models.json` |
+| | `settings.json` |
+| | `sessions/` |
+| | `skills/`, `prompts/`, `themes/` |
+
+Only **extensions** are shared from the pi host dir. Everything tied to your identity, model defaults, and settings stays in selesai's own dir. This means you can keep a single set of API keys in `~/.pi/agent/auth.json` for pi, and a different set in `~/.selesai/agent/auth.json` for selesai, while both agents load the same extension code.
+
+The host directory is hardcoded to `~/.pi/agent/extensions`. If pi ever renames its config dir, selesai will silently stop loading pi's extensions — no error, the extensions just won't appear. There is no env var to override this; the path is deliberately fixed so your two installs can't drift into loading the wrong dir.
+
+## Collisions: same extension in both dirs
+
+If an extension named `pi-subagents` exists in both `~/.selesai/agent/extensions/` and `~/.pi/agent/extensions/`, selesai does **not** load both. Loading both causes split-brain problems for stateful extensions (timers, event handlers, watchers running twice with separate `state` objects), so selesai loads exactly one copy and drops the other.
+
+The "name" used for dedup is the **top-level entry name** under the extensions dir:
+
+- A packaged extension dir (e.g. `pi-subagents/` with a `package.json`) → the dir name `pi-subagents`.
+- A loose `.ts` file (e.g. `copy-turn.ts`) → the file name `copy-turn.ts`.
+
+If you fork `pi-subagents` into a dir called `my-subagents`, the names differ and both load — no collision.
+
+### Default winner
+
+Without any config, **selesai's copy wins**. The pi copy is dropped entirely (never loaded), and a warning is printed at startup:
+
+```
+Warning: Extension "pi-subagents" exists in both ~/.selesai/agent/extensions and ~/.pi/agent/extensions; loaded the selesai copy, skipped the other. Set "extensionHost": { "pi-subagents": "pi" } or "selesai" in settings.json to change the winner.
+```
+
+## Picking the winner: `extensionHost`
+
+You control the winner per extension in `~/.selesai/agent/settings.json`:
+
+```json
+{
+  "extensionHost": {
+    "pi-subagents": "pi",
+    "copy-turn.ts": "selesai"
+  }
+}
+```
+
+| Value | Behavior |
+|---|---|
+| `"selesai"` | selesai's copy loads, pi's is dropped. |
+| `"pi"` | pi's copy loads, selesai's is dropped. |
+| (omitted) | Default applies (= selesai wins). |
+
+Typical reasons to pick `"pi"`:
+- You hack on an extension under `~/.pi/agent/extensions/` and want both agents to run your working copy.
+- pi's version is newer and you have not ported your changes into selesai yet.
+- An extension carries host-specific state (a socket path, a lockfile).
+
+Typical reasons to leave it at `"selesai"` (default):
+- You have a selesai-specific fork and want it to shadow pi's.
+- You are migrating toward selesai and are phasing pi's copy out.
+
+The setting is scoped by name, so you can mix: keep pi's `pi-subagents` but use selesai's `copy-turn.ts`.
+
+### Where to put it
+
+Global (`~/.selesai/agent/settings.json`) applies to every project. Project-local `.selesai/settings.json` (or `.pi/settings.json` inside a trusted project) overrides per project, since project settings merge on top of global. See [settings.md](settings.md) for the full merge rules.
+
+## Workflow: running pi and selesai side by side
+
+1. Keep your current install as-is:
+   ```
+   ~/.pi/agent/
+     extensions/      <- your shared extensions live here
+     auth.json
+     settings.json
+   ~/.selesai/agent/
+     extensions/      <- (optional) selesai-specific forks override the above
+     auth.json        <- separate keys, separate sessions
+     settings.json    <- add extensionHost here
+   ```
+2. If you hit a collision warning and want the other copy, add one line to `~/.selesai/agent/settings.json`:
+   ```json
+   { "extensionHost": { "pi-subagents": "pi" } }
+   ```
+3. Restart. The warning now reads that pi's copy won and selesai's was skipped.
+
+## How detection works (under the hood)
+
+- During resource resolution, selesai collects all enabled extensions from `~/.selesai/agent/extensions/`, then walks `~/.pi/agent/extensions/` for the rest.
+- For each pi-host entry, it computes the top-level entry name and checks it against the selesai set.
+- On a match, `extensionHost[name]` decides the winner; the loser is removed from the resolved set before anything loads, so no double-load of factories, no orphaned timers.
+- Each drop is recorded as a collision and surfaced as a startup warning (see [Settings](settings.md) for where diagnostics are reported).
+
+## Limitations
+
+- **Only extensions are shared.** Skills, prompts, and themes in `~/.pi/agent/skills/` etc. are never read by selesai. Copy them into `~/.selesai/agent/` if you want them.
+- **Only name collisions are deduped.** If two unrelated extensions register the same tool or command name (e.g. both define `/foo`), that conflict is handled by pi's normal first-registration-wins rule after load, not by `extensionHost`.
+- **No version check.** If selesai's `pi-subagents` is 0.2.0 and pi's is 0.4.0, `extensionHost: { "pi-subagents": "pi" }` silently loads 0.4.0. Picking the winner is purely by install location, not by version. You are responsible for matching versions when you want consistent behavior.
+- **Hardcoded host path.** If you rename pi's config dir away from `~/.pi`, selesai stops seeing it. There is no resolver hook yet.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@selesai/code",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"description": "Selesai coding agent",
 	"type": "module",
 	"piConfig": {