pi-btw 0.6.1 → 0.7.1

package/README.md

@@ -23,7 +23,11 @@ A small [pi](https://github.com/earendil-works/pi-mono) extension that adds a `/
 
 ## Install
 
-pi-btw requires Pi 0.85.1 or newer.
+pi-btw supports Pi 0.85.1 through 1.x.
+
+Development dependencies target Pi 0.99.2. CI runs the tests and typecheck
+against the locked dependencies, Pi 0.85.1, and the latest published Pi release
+on each PR and weekly. Pi 0.99.2 requires Node.js 22.19.0 or newer.
 
 ### From npm (after publish)
 
@@ -174,8 +178,53 @@ BTW is implemented as an actual pi sub-session with its own in-memory session st
 - BTW can inherit the main thread model/thinking settings or use BTW-only overrides via `/btw:model` and `/btw:thinking`
 - `/btw:summarize` uses the current effective BTW model but keeps thinking off
 - the overlay transcript/status line is driven from sub-session events, so tool activity, streaming deltas, failures, and recovery are all visible without scraping rendered output
+- child prompts preserve the main session's instructions and append an authoritative list of their own tools; inherited tool/skill instructions and historical tool calls do not grant additional capabilities
 - handoff commands (`/btw:inject` and `/btw:summarize`) read from the BTW sub-session thread rather than maintaining a separate manual transcript model
 
+### Opt-in extension tools
+
+BTW loads no extensions by default. To enable tools such as `web_search` and
+`fetch_content` in `/btw`, `/side`, and `/btw:tangent`, create
+`~/.pi/agent/btw.json` (or `btw.json` in your `PI_CODING_AGENT_DIR`):
+
+```json
+{
+  "extensions": ["npm:pi-web-access"]
+}
+```
+
+A trusted project's `.pi/btw.json` can override this list. Lists replace rather
+than merge; `{"extensions": []}` disables global BTW extensions for that
+project. An omitted `extensions` key inherits the global list. Untrusted
+projects do not contribute configuration. Config is read when a child session
+is created; use `/btw:clear` to apply changes to an existing thread.
+
+Sources can be Pi `npm:` or `git:` packages, or local extension files/package
+directories. Local paths are relative to the config file's directory. Remote
+packages are resolved into a separate BTW cache under the agent directory's
+`btw/` folder and can be installed on first use. Pin a source version when you
+need reproducible behavior.
+
+Only listed sources are loaded. BTW runs their lifecycle handlers headlessly
+(`ctx.hasUI === false`) and exposes their tools alongside `read`, `bash`,
+`edit`, and `write`, including tools registered at startup. The capability
+note follows the child's active tools. Load/startup errors stop child creation
+and are reported with the failing source; clear, mode/model changes, and parent
+shutdown run extension cleanup before disposal.
+
+Choose extensions that support headless sessions. Tools requiring interactive
+dialogs (such as `ask_user`) need additional UI integration. BTW does not import
+extension skills, prompt templates, themes, widgets, or shortcuts into its UI.
+Extensions are trusted code, not sandboxed: separate package installs avoid
+sharing the parent's cached extension factory, but extensions may still use
+shared files or external services. A local source already registered by the
+parent is rejected; use an `npm:` or `git:` source for a separate install.
+
+`/btw:ask` never reads this configuration or loads extension tools, so it retains
+its built-in read-only tool set. `/btw:summarize` remains tool-free. Extension
+configuration is machine/project configuration, not persisted in hidden
+conversation-history entries.
+
 ### In-modal slash behavior
 
 Inside the BTW modal composer, slash handling is split at the BTW/session boundary:

package/extensions/btw-extension-tools.ts

@@ -0,0 +1,111 @@
+import { readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import {
+  DefaultPackageManager,
+  DefaultResourceLoader,
+  SettingsManager,
+  type ResourceLoader,
+} from "@earendil-works/pi-coding-agent";
+
+/** Resolve local paths relative to the config that owns them, not process.cwd(). */
+function resolveSource(source: string, configPath: string): string {
+  if (source.startsWith("npm:") || source.startsWith("git:")) return source;
+  if (source.startsWith("~/")) return join(homedir(), source.slice(2));
+  return resolve(dirname(configPath), source);
+}
+
+async function readSources(path: string): Promise<string[] | undefined> {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw new Error(`Cannot read BTW config ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  let config: unknown;
+  try {
+    config = JSON.parse(text);
+  } catch {
+    throw new Error(`Invalid BTW config ${path}: expected JSON.`);
+  }
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    throw new Error(`Invalid BTW config ${path}: expected an object.`);
+  }
+  const fields = Object.keys(config);
+  if (fields.some((field) => field !== "extensions")) {
+    throw new Error(`Invalid BTW config ${path}: only the "extensions" key is supported.`);
+  }
+  if (!("extensions" in config)) return undefined;
+  if (!Array.isArray(config.extensions) || config.extensions.some((source) => typeof source !== "string" || !source.trim())) {
+    throw new Error(`Invalid BTW config ${path}: "extensions" must be an array of nonempty source strings.`);
+  }
+  return [...new Set(config.extensions.map((source: string) => resolveSource(source.trim(), path)))];
+}
+
+/** Project lists replace global lists, including an explicit empty list. */
+export async function readBtwExtensionSources(options: {
+  cwd: string;
+  agentDir: string;
+  projectTrusted: boolean;
+}): Promise<string[]> {
+  const globalSources = await readSources(join(options.agentDir, "btw.json"));
+  const projectSources = options.projectTrusted
+    ? await readSources(join(options.cwd, ".pi", "btw.json"))
+    : undefined;
+  return projectSources ?? globalSources ?? [];
+}
+
+async function canonicalPath(path: string): Promise<string> {
+  try {
+    return await realpath(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+/**
+ * Resolve the allowlist before running any extension factories. Remote packages
+ * have a BTW-owned install root so Pi's factory cache cannot reuse the parent's
+ * module globals. Local sources already loaded by the parent are rejected.
+ */
+export async function loadBtwExtensionResources(options: {
+  cwd: string;
+  agentDir: string;
+  sources: string[];
+  parentExtensionPaths: string[];
+}): Promise<ResourceLoader> {
+  const agentDir = join(options.agentDir, "btw");
+  const settingsManager = SettingsManager.inMemory();
+  const packages = new DefaultPackageManager({ cwd: options.cwd, agentDir, settingsManager });
+  const selectedPaths = new Set<string>();
+  for (const source of options.sources) {
+    const resolved = await packages.resolveExtensionSources([source], { temporary: true });
+    const paths = resolved.extensions.filter((resource) => resource.enabled).map((resource) => resource.path);
+    if (paths.length === 0) throw new Error(`BTW source ${source} did not resolve to any extensions.`);
+    for (const path of paths) selectedPaths.add(path);
+  }
+  const paths = [...selectedPaths];
+  const parentPaths = new Set(await Promise.all(options.parentExtensionPaths.map(canonicalPath)));
+  for (const path of paths) {
+    if (parentPaths.has(await canonicalPath(path))) {
+      throw new Error(
+        `BTW cannot reload the parent's extension ${path}: Pi can share its module state. Use an npm: or git: source for a separate BTW install.`,
+      );
+    }
+  }
+  const loader = new DefaultResourceLoader({
+    cwd: options.cwd,
+    agentDir,
+    settingsManager,
+    noExtensions: true,
+    noSkills: true,
+    noPromptTemplates: true,
+    noThemes: true,
+    noContextFiles: true,
+    additionalExtensionPaths: paths,
+  });
+  await loader.reload();
+  return loader;
+}

package/extensions/btw.ts

@@ -2,6 +2,7 @@ import {
   buildSessionContext,
   createAgentSession,
   createExtensionRuntime,
+  getAgentDir,
   getMarkdownTheme,
   ModelRuntime,
   SessionManager,
@@ -38,6 +39,7 @@ import {
   type OverlayOptions,
   type TUI,
 } from "@earendil-works/pi-tui";
+import { loadBtwExtensionResources, readBtwExtensionSources } from "./btw-extension-tools";
 
 const BTW_MESSAGE_TYPE = "btw-note";
 const BTW_ENTRY_TYPE = "btw-thread-entry";
@@ -270,6 +272,7 @@ type BtwSessionRuntime = {
   sideThreadStartIndex: number;
   abortPromise?: Promise<void>;
   promptQueue: Promise<void>;
+  hasExtensions: boolean;
 };
 
 type OverlayRuntime = {
@@ -298,10 +301,28 @@ function stripDynamicSystemPromptFooter(systemPrompt: string): string {
 
 function createBtwResourceLoader(
   ctx: ExtensionCommandContext,
+  tools: readonly string[] | (() => readonly string[]),
   appendSystemPrompt: string[] = [BTW_SYSTEM_PROMPT],
+  extensionResources?: ResourceLoader,
 ): ResourceLoader {
-  const extensionsResult = { extensions: [], errors: [], runtime: createExtensionRuntime() };
+  const extensionsResult = extensionResources?.getExtensions() ?? { extensions: [], errors: [], runtime: createExtensionRuntime() };
   const systemPrompt = stripDynamicSystemPromptFooter(ctx.getSystemPrompt());
+  // Preserve the parent's project/custom instructions, but override capability
+  // claims in its rendered prompt and in the history seeded into this child.
+  const capabilities = () => {
+    const availableTools = typeof tools === "function" ? tools() : tools;
+    return [
+      "<btw_capabilities>",
+      availableTools.length > 0
+        ? `Available tools in this BTW session: ${availableTools.join(", ")}.`
+        : "No tools are available in this BTW session.",
+      "This capability list is authoritative for this child session.",
+      "Tool and skill instructions inherited from the main session may describe tools that are unavailable here.",
+      "Previous tool calls in inherited conversation are historical context, not available capabilities.",
+      "Only call tools listed above; do not infer additional tools from the main session.",
+      "</btw_capabilities>",
+    ].join("\n");
+  };
 
   const resourceLoader: ResourceLoader = {
     getExtensions: () => extensionsResult,
@@ -311,7 +332,7 @@ function createBtwResourceLoader(
     getAgentsFiles: () => ({ agentsFiles: [] }),
     getSystemPrompt: () => systemPrompt,
     getSystemPromptSource: () => undefined,
-    getAppendSystemPrompt: () => appendSystemPrompt,
+    getAppendSystemPrompt: () => [...appendSystemPrompt, capabilities()],
     getAppendSystemPromptSources: () => [],
     extendResources: () => {},
     reload: async (_options) => {},
@@ -1628,6 +1649,7 @@ export default function (pi: ExtensionAPI) {
   let activeBtwSession: BtwSessionRuntime | null = null;
   let btwLifecycleGeneration = 0;
   let btwSubmissionQueue = Promise.resolve();
+  let btwSessionCreationQueue = Promise.resolve();
 
   function invalidateBtwLifecycle(): void {
     btwLifecycleGeneration += 1;
@@ -1803,7 +1825,17 @@ export default function (pi: ExtensionAPI) {
 
     clearBtwSessionSubscriptions(current);
     await requestBtwSessionAbort(current);
-    current.session.dispose();
+    await disposeChildSession(current.session, current.hasExtensions);
+  }
+
+  async function disposeChildSession(session: AgentSession, hasExtensions: boolean): Promise<void> {
+    try {
+      if (hasExtensions) {
+        await session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" });
+      }
+    } finally {
+      session.dispose();
+    }
   }
 
   async function dismissOverlaySession(): Promise<void> {
@@ -1974,8 +2006,23 @@ export default function (pi: ExtensionAPI) {
       throw new Error(settings.fallbackReason || "No active model selected.");
     }
 
+    const agentDir = getAgentDir();
+    const sources = mode === "readonly" ? [] : await readBtwExtensionSources({
+      cwd: ctx.cwd,
+      agentDir,
+      projectTrusted: ctx.isProjectTrusted(),
+    });
     const modelRuntimeOptions = await createBtwModelRuntimeOptions(ctx, settings.model);
-    const sessionManager = SessionManager.inMemory();
+    const extensionResources = sources.length > 0 ? await loadBtwExtensionResources({
+      cwd: ctx.cwd,
+      agentDir,
+      sources,
+      parentExtensionPaths: [
+        ...pi.getAllTools().map((tool) => tool.sourceInfo.path),
+        ...pi.getCommands().flatMap((command) => command.sourceInfo ? [command.sourceInfo.path] : []),
+      ],
+    }) : undefined;
+    const sessionManager = SessionManager.inMemory(ctx.cwd);
     const { messages: seedMessages, sideThreadStartIndex } = buildBtwSeedState(ctx, pendingThread, mode, settings.model);
 
     // The session manager is the source of provider context. Seed it before
@@ -1984,23 +2031,85 @@ export default function (pi: ExtensionAPI) {
       sessionManager.appendMessage(message);
     }
 
+    const builtinTools = BTW_TOOLS_BY_MODE[mode];
+    let childSession: AgentSession | undefined;
     const sessionOptions: CreateAgentSessionOptions = {
+      cwd: ctx.cwd,
       sessionManager,
       model: settings.model,
       ...modelRuntimeOptions,
       thinkingLevel: settings.thinkingLevel,
-      // Read-only mode narrows this to pi's built-in read-only toolset.
-      tools: [...BTW_TOOLS_BY_MODE[mode]],
-      resourceLoader: createBtwResourceLoader(ctx),
+      // Extension sessions need a live registry for tools registered at startup
+      // or later. Read-only sessions keep the structural built-in allowlist.
+      ...(extensionResources ? { noTools: "builtin" as const } : { tools: [...builtinTools] }),
+      resourceLoader: createBtwResourceLoader(
+        ctx, () => childSession?.getActiveToolNames() ?? builtinTools, [BTW_SYSTEM_PROMPT], extensionResources,
+      ),
     };
-    const { session } = await createAgentSession(sessionOptions);
+    const { session, extensionsResult } = await createAgentSession(sessionOptions);
+    childSession = session;
+    const hasExtensions = !!extensionResources;
+    if (hasExtensions) {
+      try {
+        if (extensionsResult.errors.length > 0) {
+          throw new Error(extensionsResult.errors.map((error) => `${error.path}: ${error.error}`).join("\n"));
+        }
+        const collectToolNames = () => {
+          const builtinNames = new Set(["read", "bash", "edit", "write", "grep", "find", "ls", "powershell"]);
+          const extensionNames = new Set<string>();
+          for (const extension of extensionsResult.extensions) {
+            for (const name of extension.tools.keys()) {
+              if (builtinNames.has(name) || extensionNames.has(name)) {
+                throw new Error(`BTW extension tool name collision: ${name}.`);
+              }
+              extensionNames.add(name);
+            }
+          }
+          return [...extensionNames];
+        };
+        session.setActiveToolsByName([...builtinTools, ...collectToolNames()]);
+        const startupErrors: string[] = [];
+        let starting = true;
+        await session.bindExtensions({
+          onError: (error) => {
+            const message = `${error.extensionPath}: ${error.error}`;
+            if (starting) startupErrors.push(message);
+            else notify(ctx, `BTW extension error: ${message}`, "error");
+          },
+        });
+        starting = false;
+        if (startupErrors.length > 0) throw new Error(startupErrors.join("\n"));
+        collectToolNames();
+      } catch (error) {
+        try {
+          await session.abort();
+        } finally {
+          await disposeChildSession(session, true);
+        }
+        throw error;
+      }
+    }
 
-    return { session, mode, subscriptions: new Set(), sideThreadStartIndex, promptQueue: Promise.resolve() };
+    return { session, mode, subscriptions: new Set(), sideThreadStartIndex, promptQueue: Promise.resolve(), hasExtensions };
+  }
+
+  function ensureBtwSession(ctx: ExtensionCommandContext, mode: BtwThreadMode): Promise<BtwSessionRuntime | null> {
+    const generation = btwLifecycleGeneration;
+    // Composer-only commands can overlap while npm resolution is in flight.
+    // Serialize creation so they reuse one child and never race package installs.
+    const creation = btwSessionCreationQueue.then(() => createOrReuseBtwSession(ctx, mode, generation));
+    btwSessionCreationQueue = creation.then(() => {}, () => {});
+    return creation;
   }
 
-  async function ensureBtwSession(ctx: ExtensionCommandContext, mode: BtwThreadMode): Promise<BtwSessionRuntime | null> {
+  async function createOrReuseBtwSession(
+    ctx: ExtensionCommandContext,
+    mode: BtwThreadMode,
+    generation: number,
+  ): Promise<BtwSessionRuntime | null> {
+    if (generation !== btwLifecycleGeneration) return null;
     const settings = await resolveBtwSettings(ctx, true);
-    if (!settings.model) {
+    if (generation !== btwLifecycleGeneration || !settings.model) {
       return null;
     }
 
@@ -2009,7 +2118,22 @@ export default function (pi: ExtensionAPI) {
     }
 
     await disposeBtwSession();
-    activeBtwSession = await createBtwSubSession(ctx, mode, settings);
+    if (generation !== btwLifecycleGeneration) return null;
+    try {
+      const created = await createBtwSubSession(ctx, mode, settings);
+      if (generation !== btwLifecycleGeneration) {
+        await requestBtwSessionAbort(created);
+        await disposeChildSession(created.session, created.hasExtensions);
+        return null;
+      }
+      activeBtwSession = created;
+    } catch (error) {
+      if (generation !== btwLifecycleGeneration) return null;
+      const message = `Could not start BTW session: ${error instanceof Error ? error.message : String(error)}`;
+      setOverlayStatus(message, ctx);
+      notify(ctx, message, "error");
+      return null;
+    }
     return activeBtwSession;
   }
 
@@ -2501,8 +2625,6 @@ export default function (pi: ExtensionAPI) {
       return;
     }
     if (!sessionRuntime) {
-      setOverlayStatus("No active model selected.", ctx);
-      notify(ctx, "No active model selected.", "error");
       return;
     }
 
@@ -2670,7 +2792,7 @@ export default function (pi: ExtensionAPI) {
       ...modelRuntimeOptions,
       thinkingLevel: "off",
       tools: [],
-      resourceLoader: createBtwResourceLoader(ctx, [BTW_SUMMARIZE_SYSTEM_PROMPT]),
+      resourceLoader: createBtwResourceLoader(ctx, [], [BTW_SUMMARIZE_SYSTEM_PROMPT]),
     };
     const { session } = await createAgentSession(sessionOptions);
 
@@ -2861,4 +2983,3 @@ export default function (pi: ExtensionAPI) {
     },
   });
 }
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-btw",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "A pi extension for parallel side conversations with /btw",
   "type": "module",
   "license": "MIT",
@@ -44,15 +44,15 @@
     "image": "https://raw.githubusercontent.com/dbachelder/pi-btw/main/docs/btw-overlay.png"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.85.1 <1",
-    "@earendil-works/pi-coding-agent": ">=0.85.1 <1",
-    "@earendil-works/pi-tui": ">=0.85.1 <1"
+    "@earendil-works/pi-ai": ">=0.85.1 <2",
+    "@earendil-works/pi-coding-agent": ">=0.85.1 <2",
+    "@earendil-works/pi-tui": ">=0.85.1 <2"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.87.1",
-    "@earendil-works/pi-coding-agent": "0.87.1",
-    "@earendil-works/pi-tui": "0.87.1",
+    "@earendil-works/pi-ai": "0.99.2",
+    "@earendil-works/pi-coding-agent": "0.99.2",
+    "@earendil-works/pi-tui": "0.99.2",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.11"
   }
 }