pi-btw 0.7.1 → 0.8.0

package/README.md

@@ -220,16 +220,57 @@ 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
+`/btw:ask` ignores the `extensions` setting and never loads extension tools.
+It reads only the workspace selection and retains its read-only tool set. `/btw:summarize` remains tool-free. Extension
 configuration is machine/project configuration, not persisted in hidden
 conversation-history entries.
 
+### SSH workspaces
+
+BTW uses local tools by default, even when the parent uses an SSH workspace.
+The overlay identifies its workspace, and the capability note tells the child
+where its tools operate. To use the active parent SSH workspace, set this in
+`~/.pi/agent/btw.json` or a trusted project's `.pi/btw.json`:
+
+```json
+{
+  "workspace": "ssh"
+}
+```
+
+This requires `@99percentpeople/pi-ssh-remote` 0.6.2 or newer in the parent.
+Do not add that package to BTW's `extensions` list. BTW uses its public transport
+and remote adapter APIs directly, creates a separate connection to the parent's
+selected target/port/directory, and never runs its extension factory or lifecycle
+handlers. Authentication uses SSH keys, your SSH agent, and the parent's SSH
+config file; BTW does not copy passwords or open password dialogs.
+
+`/btw`, `/side`, and `/btw:tangent` expose remote `read`, `bash`, `edit`, and
+`write`. `/btw:ask` exposes only remote `read`, `grep`, `find`, and `ls` and
+still loads no arbitrary extensions. Connection and tool failures are reported;
+there is no fallback to local operations. Local instructions and session files
+remain local, and remote shells use the remote environment.
+
+Use `/btw:clear` after changing the parent host/directory, running `/ssh-exit`,
+or changing workspace configuration. An existing remote thread blocks further
+operations after parent workspace changes or disconnects, and saved threads
+cannot resume against a different workspace. A new SSH thread requires an active
+parent SSH workspace. Set `"workspace": "local"` to select local tools explicitly.
+The project setting overrides the global setting independently of `extensions`;
+untrusted project settings are ignored.
+
 ### In-modal slash behavior
 
+Type `/` at the start of the composer to see BTW-owned commands. Keep typing to
+filter, use Up/Down to select, and Tab or Enter to complete a partial command.
+Completion inserts the command and a trailing space without submitting. Enter on
+an exact command or with arguments submits normally. Escape closes the list
+first; a subsequent Escape keeps the existing abort/dismiss behavior. The menu
+shares space with the transcript rather than growing the modal.
+
 Inside the BTW modal composer, slash handling is split at the BTW/session boundary:
 
-- `/btw:new`, `/btw:tangent`, `/btw:ask`, `/btw:clear`, `/btw:model`, `/btw:thinking`, `/btw:inject`, and `/btw:summarize` stay owned by BTW because they control BTW lifecycle, configuration, or handoff behavior
+- `/btw`, `/side`, `/btw:new`, `/btw:tangent`, `/btw:ask`, `/btw:clear`, `/btw:model`, `/btw:thinking`, `/btw:inject`, and `/btw:summarize` stay owned by BTW because they control BTW lifecycle, configuration, or handoff behavior
 - any other slash-prefixed input is routed through the BTW sub-session's normal `prompt()` path
 - this means ordinary pi slash commands like `/help` are handled by the sub-session instead of being rejected by a modal-only fallback
 - if the sub-session cannot handle a slash command, BTW surfaces the real sub-session failure through the transcript/status state instead of inventing an "unsupported slash input" warning

package/extensions/btw-extension-tools.ts

@@ -15,7 +15,9 @@ function resolveSource(source: string, configPath: string): string {
   return resolve(dirname(configPath), source);
 }
 
-async function readSources(path: string): Promise<string[] | undefined> {
+type BtwConfig = { extensions?: string[]; workspace?: "local" | "ssh" };
+
+async function readConfig(path: string, includeExtensions = true): Promise<BtwConfig | undefined> {
   let text: string;
   try {
     text = await readFile(path, "utf8");
@@ -34,14 +36,19 @@ async function readSources(path: string): Promise<string[] | undefined> {
     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 (fields.some((field) => field !== "extensions" && field !== "workspace")) {
+    throw new Error(`Invalid BTW config ${path}: only "extensions" and "workspace" keys are supported.`);
+  }
+  if ("workspace" in config && config.workspace !== "local" && config.workspace !== "ssh") {
+    throw new Error(`Invalid BTW config ${path}: "workspace" must be "local" or "ssh".`);
   }
-  if (!("extensions" in config)) return undefined;
-  if (!Array.isArray(config.extensions) || config.extensions.some((source) => typeof source !== "string" || !source.trim())) {
+  if (includeExtensions && "extensions" in config && (!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)))];
+  return {
+    ...(includeExtensions && "extensions" in config && Array.isArray(config.extensions) ? { extensions: [...new Set(config.extensions.map((source: string) => resolveSource(source.trim(), path)))] } : {}),
+    ...("workspace" in config ? { workspace: config.workspace as "local" | "ssh" } : {}),
+  };
 }
 
 /** Project lists replace global lists, including an explicit empty list. */
@@ -50,11 +57,22 @@ export async function readBtwExtensionSources(options: {
   agentDir: string;
   projectTrusted: boolean;
 }): Promise<string[]> {
-  const globalSources = await readSources(join(options.agentDir, "btw.json"));
+  const globalSources = await readConfig(join(options.agentDir, "btw.json"));
   const projectSources = options.projectTrusted
-    ? await readSources(join(options.cwd, ".pi", "btw.json"))
+    ? await readConfig(join(options.cwd, ".pi", "btw.json"))
     : undefined;
-  return projectSources ?? globalSources ?? [];
+  return projectSources?.extensions ?? globalSources?.extensions ?? [];
+}
+
+/** Workspace selection is independent of extension tool loading, including ask mode. */
+export async function readBtwWorkspaceMode(options: {
+  cwd: string;
+  agentDir: string;
+  projectTrusted: boolean;
+}): Promise<"local" | "ssh"> {
+  const globalConfig = await readConfig(join(options.agentDir, "btw.json"), false);
+  const projectConfig = options.projectTrusted ? await readConfig(join(options.cwd, ".pi", "btw.json"), false) : undefined;
+  return projectConfig?.workspace ?? globalConfig?.workspace ?? "local";
 }
 
 async function canonicalPath(path: string): Promise<string> {

package/extensions/btw-ssh-workspace.ts

@@ -0,0 +1,254 @@
+import { pathToFileURL } from "node:url";
+import {
+  createReadToolDefinition, createWriteToolDefinition, createEditToolDefinition,
+  createBashToolDefinition, createGrepToolDefinition, createFindToolDefinition,
+  createLsToolDefinition, defineTool, truncateHead, truncateLine,
+  type ExtensionAPI, type ExtensionCommandContext, type ToolDefinition,
+  type AgentToolResult, type BashOperations,
+} from "@earendil-works/pi-coding-agent";
+
+type SshState = {
+  target: string; port?: number; configFile?: string; remoteCwd: string;
+  remoteHome: string; remotePlatform: string; remoteShell: string;
+};
+type Workspace = { cwd: string; home: string; platform: string; shell: string };
+type Entry = { path: string; isDirectory: boolean };
+type Match = { path: string; toolPath: string; lineNumber: number; line: string };
+
+// The published SSH extension exposes these backend APIs independently of its
+// default extension factory. Importing them does not start or stop the parent.
+type Adapter = {
+  toToolPath(path: string, workspace: Workspace): string;
+  mapCwd(path: string, localCwd: string, workspace: Workspace): string;
+  readFile(path: string, signal?: AbortSignal): Promise<Buffer>;
+  access(path: string, mode: "read" | "write", signal?: AbortSignal): Promise<void>;
+  detectImageMimeType(path: string, signal?: AbortSignal): Promise<string | null>;
+  mkdir(path: string, signal?: AbortSignal): Promise<void>;
+  writeFile(path: string, data: Buffer | string, signal?: AbortSignal): Promise<void>;
+  runShell(command: string, cwd: string, options: {
+    signal?: AbortSignal; timeoutSeconds?: number; env?: NodeJS.ProcessEnv;
+    captureOutput: boolean; onStdout: (data: Buffer) => void; onStderr: (data: Buffer) => void;
+  }): Promise<number | null>;
+  listDirectory(path: string, signal?: AbortSignal): Promise<Array<{ name: string; isDirectory: boolean }>>;
+  findEntries(path: string, pattern: string, limit: number, signal?: AbortSignal): Promise<Entry[]>;
+  grep(path: string, pattern: string, options: {
+    glob?: string; ignoreCase?: boolean; literal?: boolean; limit: number;
+  }, signal?: AbortSignal): Promise<Match[]>;
+};
+type Client = { dispose(): Promise<void>; onDisconnect?(handler: (error: Error) => void): () => void };
+type SshApi = {
+  findSshEnvironmentState(entries: readonly unknown[]): { mode: "local" } | { mode: "remote"; session: SshState } | undefined;
+  createSshTransportClient(options: {
+    target: string; port?: number; configFile?: string; batchMode: boolean; connectTimeoutSeconds: number;
+  }, settings: { platform: NodeJS.Platform; preference: "auto" }): Client;
+  selectRemoteAdapter(client: Client, options: {
+    localPlatform: NodeJS.Platform; preference: string; expectedPlatform: string;
+    expectedShell: string; requestedCwd: string;
+  }): Promise<{ adapter: Adapter; workspace: Workspace }>;
+};
+
+export type BtwSshWorkspace = {
+  label: string;
+  identity: string;
+  tools: ToolDefinition[];
+  assertCurrent(): void;
+  dispose(): Promise<void>;
+};
+
+function limit(value: number | undefined, fallback: number): number {
+  if (value === undefined) return fallback;
+  if (!Number.isFinite(value) || value <= 0) throw new Error("Limit must be a positive finite number.");
+  return Math.max(1, Math.floor(value));
+}
+
+type SearchDetails = {
+  truncation?: ReturnType<typeof truncateHead>; entryLimitReached?: number;
+  resultLimitReached?: number; matchLimitReached?: number;
+};
+
+function textResult(text: string, details: SearchDetails = {}): AgentToolResult<SearchDetails> {
+  const truncation = truncateHead(text, { maxLines: Number.MAX_SAFE_INTEGER });
+  if (truncation.truncated) details.truncation = truncation;
+  const notices = Object.entries(details).filter(([key]) => key.endsWith("LimitReached"))
+    .map(([, value]) => `${value} results limit reached; increase limit or narrow the search.`);
+  if (truncation.truncated) notices.push("Output truncated; narrow the search.");
+  return {
+    content: [{ type: "text", text: truncation.content + (notices.length ? `\n\n[${notices.join(" ")}]` : "") }],
+    details,
+  };
+}
+
+async function displayFileErrors<T extends AgentToolResult<unknown>>(
+  displayPath: string, toolPath: string, run: () => Promise<T>,
+): Promise<T> {
+  try {
+    // Successful results may contain literal file contents or diff lines.
+    // Never rewrite them just to make encoded remote paths prettier.
+    return await run();
+  } catch (error) {
+    throw new Error((error instanceof Error ? error.message : String(error)).replaceAll(toolPath, displayPath));
+  }
+}
+
+export async function createBtwSshWorkspace(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  readonly: boolean,
+): Promise<BtwSshWorkspace> {
+  const source = pi.getAllTools().find((tool) => tool.name === "read")?.sourceInfo.path;
+  if (!source || source.startsWith("<")) {
+    throw new Error('workspace: "ssh" requires the parent pi-ssh-remote extension (0.6.2 or newer).');
+  }
+  const api = await import(/* @vite-ignore */ pathToFileURL(source).href) as Partial<SshApi>;
+  if (!api.findSshEnvironmentState || !api.createSshTransportClient || !api.selectRemoteAdapter) {
+    throw new Error("The parent read backend does not expose the supported pi-ssh-remote APIs.");
+  }
+  const getState = () => api.findSshEnvironmentState!(ctx.sessionManager.getBranch());
+  const environment = getState();
+  if (environment?.mode !== "remote") {
+    throw new Error('No active parent SSH workspace. Connect SSH first, or select workspace: "local".');
+  }
+  const state = environment.session;
+  const signature = JSON.stringify(state);
+  let unavailable: string | undefined;
+  let disposed = false;
+  const assertCurrent = () => {
+    const current = getState();
+    if (disposed || unavailable || current?.mode !== "remote" || JSON.stringify(current.session) !== signature) {
+      throw new Error(`${unavailable ?? "Parent SSH workspace changed."} Run /btw:clear before continuing.`);
+    }
+  };
+  const unsubscribe = pi.events.on("ssh-remote:environment", () => {
+    unavailable = "Parent SSH workspace changed.";
+  });
+  let client: Client | undefined;
+  let removeDisconnectListener: (() => void) | undefined;
+  const dispose = async () => {
+    if (disposed) return;
+    disposed = true;
+    unsubscribe();
+    removeDisconnectListener?.();
+    await client?.dispose();
+  };
+
+  try {
+    client = api.createSshTransportClient({
+      target: state.target, port: state.port, configFile: state.configFile,
+      batchMode: true, connectTimeoutSeconds: 10,
+    }, { platform: process.platform, preference: "auto" });
+    const { adapter, workspace } = await api.selectRemoteAdapter(client, {
+      localPlatform: process.platform, preference: state.remoteShell,
+      expectedPlatform: state.remotePlatform, expectedShell: state.remoteShell, requestedCwd: state.remoteCwd,
+    });
+    removeDisconnectListener = client.onDisconnect?.((error) => { unavailable = `BTW SSH disconnected: ${error.message}`; });
+    assertCurrent();
+    const cwd = adapter.toToolPath(workspace.cwd, workspace);
+    const filePath = (path: string) => adapter.toToolPath(path, workspace);
+    const searchPath = (path?: string) => adapter.toToolPath(adapter.mapCwd(path || ".", ctx.cwd, workspace), workspace);
+    const read = createReadToolDefinition(cwd);
+    const tools: ToolDefinition[] = [defineTool({
+      ...read,
+      async execute(id, args, signal, onUpdate, toolCtx) {
+        assertCurrent();
+        const path = filePath(args.path);
+        return displayFileErrors(args.path, path, () => createReadToolDefinition(cwd, { operations: {
+          readFile: (path) => adapter.readFile(path, signal),
+          access: (path) => adapter.access(path, "read", signal),
+          detectImageMimeType: (path) => adapter.detectImageMimeType(path, signal),
+        } }).execute(id, { ...args, path }, signal, onUpdate, toolCtx));
+      },
+    })];
+
+    if (readonly) {
+      tools.push(defineTool({
+        ...createLsToolDefinition(cwd),
+        async execute(_id, args, signal) {
+          assertCurrent();
+          const count = limit(args.limit, 500);
+          const entries = (await adapter.listDirectory(searchPath(args.path), signal))
+            .sort((a, b) => a.name.localeCompare(b.name));
+          return textResult(entries.slice(0, count).map((entry) => entry.name + (entry.isDirectory ? "/" : "")).join("\n") || "(empty directory)",
+            entries.length > count ? { entryLimitReached: count } : {});
+        },
+      }), defineTool({
+        ...createFindToolDefinition(cwd),
+        async execute(_id, args, signal) {
+          assertCurrent();
+          const count = limit(args.limit, 1000);
+          const entries = await adapter.findEntries(searchPath(args.path), args.pattern, count + 1, signal);
+          return textResult(entries.slice(0, count).map((entry) => entry.path + (entry.isDirectory ? "/" : "")).join("\n") || "No files found matching pattern",
+            entries.length > count ? { resultLimitReached: count } : {});
+        },
+      }), defineTool({
+        ...createGrepToolDefinition(cwd),
+        async execute(_id, args, signal) {
+          assertCurrent();
+          const count = limit(args.limit, 100);
+          const matches = await adapter.grep(searchPath(args.path), args.pattern, {
+            glob: args.glob, ignoreCase: args.ignoreCase, literal: args.literal, limit: count + 1,
+          }, signal);
+          const context = args.context === undefined ? 0 : Math.max(0, Math.floor(args.context));
+          if (!Number.isFinite(context)) throw new Error("Context must be a finite number.");
+          const lines: string[] = [];
+          const files = new Map<string, string[]>();
+          for (const match of matches.slice(0, count)) {
+            signal?.throwIfAborted();
+            if (!context) {
+              lines.push(`${match.path}:${match.lineNumber}: ${truncateLine(match.line).text}`);
+              continue;
+            }
+            let content = files.get(match.toolPath);
+            if (!content) {
+              content = (await adapter.readFile(match.toolPath, signal)).toString("utf8").replace(/\r\n/g, "\n").split("\n");
+              files.set(match.toolPath, content);
+            }
+            for (let line = Math.max(1, match.lineNumber - context); line <= Math.min(content.length, match.lineNumber + context); line++) {
+              const separator = line === match.lineNumber ? ":" : "-";
+              lines.push(`${match.path}${separator}${line}${separator} ${truncateLine(content[line - 1]).text}`);
+            }
+          }
+          return textResult(lines.join("\n") || "No matches found", matches.length > count ? { matchLimitReached: count } : {});
+        },
+      }));
+    } else {
+      tools.push(defineTool({
+        ...createWriteToolDefinition(cwd),
+        async execute(id, args, signal, onUpdate, toolCtx) {
+          assertCurrent();
+          const path = filePath(args.path);
+          return displayFileErrors(args.path, path, () => createWriteToolDefinition(cwd, { operations: {
+            mkdir: (path) => adapter.mkdir(path, signal),
+            writeFile: (path, data) => adapter.writeFile(path, data, signal),
+          } }).execute(id, { ...args, path }, signal, onUpdate, toolCtx));
+        },
+      }), defineTool({
+        ...createEditToolDefinition(cwd),
+        async execute(id, args, signal, onUpdate, toolCtx) {
+          assertCurrent();
+          const path = filePath(args.path);
+          return displayFileErrors(args.path, path, () => createEditToolDefinition(cwd, { operations: {
+            readFile: (path) => adapter.readFile(path, signal),
+            access: (path) => adapter.access(path, "write", signal),
+            writeFile: (path, data) => adapter.writeFile(path, data, signal),
+          } }).execute(id, { ...args, path }, signal, onUpdate, toolCtx));
+        },
+      }), defineTool({
+        ...createBashToolDefinition(cwd),
+        async execute(id, args, signal, onUpdate, toolCtx) {
+          assertCurrent();
+          const operations: BashOperations = {
+            exec: async (command, _cwd, options) => ({ exitCode: await adapter.runShell(command, workspace.cwd, {
+              signal: options.signal, timeoutSeconds: options.timeout,
+              captureOutput: false, onStdout: options.onData, onStderr: options.onData,
+            }) }),
+          };
+          return createBashToolDefinition(cwd, { operations, exposeSessionEnvironment: false }).execute(id, args, signal, onUpdate, toolCtx);
+        },
+      }));
+    }
+    return { label: `SSH ${state.target}${state.port ? `:${state.port}` : ""}:${workspace.cwd}`, identity: `ssh:${signature}`, tools, assertCurrent, dispose };
+  } catch (error) {
+    await dispose();
+    throw new Error(`Could not connect BTW SSH workspace: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}

package/extensions/btw.ts

@@ -39,7 +39,21 @@ import {
   type OverlayOptions,
   type TUI,
 } from "@earendil-works/pi-tui";
-import { loadBtwExtensionResources, readBtwExtensionSources } from "./btw-extension-tools";
+import { loadBtwExtensionResources, readBtwExtensionSources, readBtwWorkspaceMode } from "./btw-extension-tools";
+import { createBtwSshWorkspace, type BtwSshWorkspace } from "./btw-ssh-workspace";
+
+export const BTW_COMMANDS = [
+  { name: "btw", description: "Continue a side conversation in a focused BTW modal. Add --save to also persist a visible note." },
+  { name: "side", description: "Alias for /btw: continue a side conversation in a focused BTW modal." },
+  { name: "btw:tangent", description: "Start or continue a contextless BTW tangent in the focused BTW modal." },
+  { name: "btw:ask", description: "Ask a read-only side question: inherits main-session context but exposes only read/grep/find/ls tools." },
+  { name: "btw:new", description: "Start a fresh BTW thread with main-session context. Optionally ask the first question immediately." },
+  { name: "btw:clear", description: "Dismiss the BTW modal/widget and clear the current thread." },
+  { name: "btw:inject", description: "Inject the full BTW thread into the main agent as a user message." },
+  { name: "btw:summarize", description: "Summarize the BTW thread, then inject the summary into the main agent." },
+  { name: "btw:model", description: "Show, set, or clear the BTW-only model override." },
+  { name: "btw:thinking", description: "Show, set, or clear the BTW-only thinking override." },
+] as const;
 
 const BTW_MESSAGE_TYPE = "btw-note";
 const BTW_ENTRY_TYPE = "btw-thread-entry";
@@ -196,6 +210,7 @@ type BtwDetails = {
   thinkingLevel: SessionThinkingLevel;
   timestamp: number;
   usage?: AssistantMessage["usage"];
+  workspaceIdentity?: string;
 };
 
 type ParsedBtwArgs = {
@@ -273,6 +288,8 @@ type BtwSessionRuntime = {
   abortPromise?: Promise<void>;
   promptQueue: Promise<void>;
   hasExtensions: boolean;
+  workspace?: BtwSshWorkspace;
+  workspaceIdentity: string;
 };
 
 type OverlayRuntime = {
@@ -304,6 +321,7 @@ function createBtwResourceLoader(
   tools: readonly string[] | (() => readonly string[]),
   appendSystemPrompt: string[] = [BTW_SYSTEM_PROMPT],
   extensionResources?: ResourceLoader,
+  workspaceLabel = `local ${ctx.cwd}`,
 ): ResourceLoader {
   const extensionsResult = extensionResources?.getExtensions() ?? { extensions: [], errors: [], runtime: createExtensionRuntime() };
   const systemPrompt = stripDynamicSystemPromptFooter(ctx.getSystemPrompt());
@@ -313,6 +331,7 @@ function createBtwResourceLoader(
     const availableTools = typeof tools === "function" ? tools() : tools;
     return [
       "<btw_capabilities>",
+      `Workspace for built-in file and shell tools: ${workspaceLabel}.`,
       availableTools.length > 0
         ? `Available tools in this BTW session: ${availableTools.join(", ")}.`
         : "No tools are available in this BTW session.",
@@ -475,6 +494,15 @@ const BTW_TOOLS_BY_MODE: Record<BtwThreadMode, readonly string[]> = {
   readonly: ["read", "grep", "find", "ls"],
 };
 
+function withoutParentToolDeclarations(message: Message): Message {
+  if ((message as { role: string }).role !== "system") return message;
+  const { toolsAdded: _added, toolsRemoved: _removed, ...rest } = message as Message & {
+    toolsAdded?: unknown;
+    toolsRemoved?: unknown;
+  };
+  return rest as Message;
+}
+
 function buildBtwSeedState(
   ctx: ExtensionCommandContext,
   thread: BtwDetails[],
@@ -488,7 +516,7 @@ function buildBtwSeedState(
       messages.push(
         ...(buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId()).messages as Message[]).filter(
           (message) => !isVisibleBtwMessage(message),
-        ),
+        ).map(withoutParentToolDeclarations),
       );
     } catch {
       messages.push(
@@ -502,7 +530,9 @@ function buildBtwSeedState(
             return [];
           }
 
-          return isVisibleBtwMessage({ role: message.role, customType: message.customType }) ? [] : [message as Message];
+          return isVisibleBtwMessage({ role: message.role, customType: message.customType })
+            ? []
+            : [withoutParentToolDeclarations(message as Message)];
         }),
       );
     }
@@ -1284,8 +1314,9 @@ function buildTranscriptBadge(
   return theme.bg(background, theme.fg(foreground, theme.bold(` ${label} `)));
 }
 
-class BtwOverlayComponent extends Container implements Focusable {
+export class BtwOverlayComponent extends Container implements Focusable {
   private readonly input: Input;
+  private readonly handleRawInput: (data: string) => void;
   private readonly transcript: Container;
   private readonly statusText: Text;
   private readonly modeText: Text;
@@ -1295,6 +1326,7 @@ class BtwOverlayComponent extends Container implements Focusable {
   private readonly getStatus: () => string | null;
   private readonly getMode: () => BtwThreadMode;
   private readonly getWidthMode: () => BtwOverlayWidthMode;
+  private readonly getWorkspaceLabel: () => string;
   private readonly onSubmitCallback: (value: string) => void;
   private readonly onDismissCallback: () => void;
   private readonly onUnfocusCallback: () => void;
@@ -1313,6 +1345,11 @@ class BtwOverlayComponent extends Container implements Focusable {
   private summaryTextValue = "";
   private statusTextValue = "";
   private hintsTextValue = "";
+  private readonly keybindings: KeybindingsManager;
+  private completionQuery = "";
+  private completionDismissedFor: string | null = null;
+  private completionItems: typeof BTW_COMMANDS[number][] = [];
+  private completionIndex = 0;
 
   get focused(): boolean {
     return this._focused;
@@ -1335,10 +1372,12 @@ class BtwOverlayComponent extends Container implements Focusable {
     onDismiss: () => void,
     onUnfocus: () => void,
     onToggleWidth: () => void,
+    getWorkspaceLabel: () => string = () => "local",
   ) {
     super();
     this.tui = tui;
     this.theme = theme;
+    this.keybindings = keybindings;
     this.markdownTheme = getMarkdownTheme();
     // Fullscreen Pi owns mouse reporting for the entire terminal session. In
     // regular mode BTW manages it while the overlay exists.
@@ -1347,6 +1386,7 @@ class BtwOverlayComponent extends Container implements Focusable {
     this.getStatus = getStatus;
     this.getMode = getMode;
     this.getWidthMode = getWidthMode;
+    this.getWorkspaceLabel = getWorkspaceLabel;
     this.onSubmitCallback = onSubmit;
     this.onDismissCallback = onDismiss;
     this.onUnfocusCallback = onUnfocus;
@@ -1373,11 +1413,11 @@ class BtwOverlayComponent extends Container implements Focusable {
     }
 
     const originalHandleInput = this.input.handleInput.bind(this.input);
+    this.handleRawInput = originalHandleInput;
     this.input.handleInput = (data: string) => {
       if (keybindings.matches(data, "app.clear")) {
         if (this.input.getValue().length > 0) {
-          this.input.setValue("");
-          this.tui.requestRender();
+          this.setDraft("");
           return;
         }
 
@@ -1385,16 +1425,60 @@ class BtwOverlayComponent extends Container implements Focusable {
         return;
       }
 
+      if (this.handleCompletionInput(data)) return;
+
       if (keybindings.matches(data, "tui.select.cancel")) {
         this.onDismissCallback();
         return;
       }
       originalHandleInput(data);
+      this.updateCompletions();
+      this.tui.requestRender();
     };
 
     this.refresh();
   }
 
+  private updateCompletions(): void {
+    const value = this.input.getValue();
+    if (value !== this.completionQuery) {
+      this.completionQuery = value;
+      this.completionIndex = 0;
+      this.completionDismissedFor = null;
+    }
+    this.completionItems = /^\/[^\s]*$/.test(value) && value !== this.completionDismissedFor
+      ? BTW_COMMANDS.filter((command) => `/${command.name}`.startsWith(value)) : [];
+  }
+
+  private handleCompletionInput(data: string): boolean {
+    this.updateCompletions();
+    if (!this.completionItems.length || this.keybindings.matches(data, "app.clear")) return false;
+    if (matchesKey(data, Key.up) || matchesKey(data, Key.down)) {
+      const delta = matchesKey(data, Key.up) ? -1 : 1;
+      this.completionIndex = (this.completionIndex + delta + this.completionItems.length) % this.completionItems.length;
+    } else if (matchesKey(data, Key.tab) || (matchesKey(data, Key.enter)
+      && !BTW_COMMANDS.some((command) => `/${command.name}` === this.input.getValue()))) {
+      this.setDraft(`/${this.completionItems[this.completionIndex].name} `);
+    } else if (this.keybindings.matches(data, "tui.select.cancel")) {
+      this.completionDismissedFor = this.input.getValue();
+      this.completionItems = [];
+    } else {
+      return false;
+    }
+    this.tui.requestRender();
+    return true;
+  }
+
+  private completionRows(): string[] {
+    this.updateCompletions();
+    const start = Math.max(0, this.completionIndex - 4);
+    return this.completionItems.slice(start, start + 5).map((command, index) => {
+      const selected = start + index === this.completionIndex;
+      return this.theme.fg(selected ? "accent" : "dim",
+        `${selected ? "→" : " "} /${command.name}  ${command.description}`);
+    });
+  }
+
   private get borderless(): boolean {
     // Full-width mode drops the vertical bars and corner glyphs so a terminal
     // Shift+drag selection captures only the dialog's own text — with side
@@ -1489,6 +1573,8 @@ class BtwOverlayComponent extends Container implements Focusable {
       return;
     }
 
+    if (this.handleCompletionInput(data)) return;
+
     if (matchesKey(data, Key.pageUp) || matchesKey(data, Key.up)) {
       const step = matchesKey(data, Key.pageUp) ? Math.max(1, this.transcriptViewportHeight - 1) : 1;
       this.scrollTranscript(-step);
@@ -1542,7 +1628,8 @@ class BtwOverlayComponent extends Container implements Focusable {
     const transcriptLines = this.wrapTranscript(innerWidth);
     const dialogHeight = this.getDialogHeight();
     const chromeHeight = BTW_OVERLAY_CHROME_LINES;
-    const transcriptHeight = Math.max(6, dialogHeight - chromeHeight);
+    const completionRows = this.completionRows();
+    const transcriptHeight = Math.max(1, dialogHeight - chromeHeight - completionRows.length);
     this.transcriptViewportHeight = transcriptHeight;
 
     const maxScroll = Math.max(0, transcriptLines.length - transcriptHeight);
@@ -1582,6 +1669,7 @@ class BtwOverlayComponent extends Container implements Focusable {
 
     lines.push(this.ruleLine(innerWidth));
     lines.push(this.frameLine(this.theme.fg("warning", this.statusTextValue.trim()), innerWidth));
+    for (const row of completionRows) lines.push(this.frameLine(row, innerWidth));
     lines.push(this.inputFrameLine(dialogWidth));
     lines.push(this.frameLine(this.theme.fg("dim", this.hintsTextValue.trim()), innerWidth));
     lines.push(this.borderLine(innerWidth, "bottom"));
@@ -1590,7 +1678,11 @@ class BtwOverlayComponent extends Container implements Focusable {
   }
 
   setDraft(value: string): void {
-    this.input.setValue(value);
+    // Input.setValue preserves the cursor. Paste into an empty input so a
+    // completed command leaves the cursor after its trailing space.
+    this.input.setValue("");
+    if (value) this.handleRawInput(`\x1b[200~${value}\x1b[201~`);
+    this.updateCompletions();
     this.tui.requestRender();
   }
 
@@ -1612,7 +1704,7 @@ class BtwOverlayComponent extends Container implements Focusable {
   }
 
   refresh(): void {
-    this.modeTextValue = `${getOverlayTitle(this.getMode())} · hidden thread preserved`;
+    this.modeTextValue = `${getOverlayTitle(this.getMode())} · ${this.getWorkspaceLabel()} · hidden thread preserved`;
     this.modeText.setText(this.modeTextValue);
     const entries = this.readTranscriptEntries();
     const exchanges = getCompletedExchangeCount(entries);
@@ -1629,7 +1721,7 @@ class BtwOverlayComponent extends Container implements Focusable {
     const status = this.getStatus() ?? "Ready. Enter submits; Escape dismisses without clearing.";
     this.statusTextValue = status;
     this.statusText.setText(this.statusTextValue);
-    this.hintsTextValue = `Scroll wheel ↑↓ PgUp/PgDn · Enter · ${BTW_FOCUS_SHORTCUTS_LABEL} focus · Alt+w width · Esc`;
+    this.hintsTextValue = `↑↓ select/scroll · Tab complete · Enter · ${BTW_FOCUS_SHORTCUTS_LABEL} focus · Alt+w width · Esc`;
     this.hintsText.setText(this.hintsTextValue);
     this.tui.requestRender();
   }
@@ -1825,16 +1917,20 @@ export default function (pi: ExtensionAPI) {
 
     clearBtwSessionSubscriptions(current);
     await requestBtwSessionAbort(current);
-    await disposeChildSession(current.session, current.hasExtensions);
+    await disposeChildSession(current.session, current.hasExtensions, current.workspace);
   }
 
-  async function disposeChildSession(session: AgentSession, hasExtensions: boolean): Promise<void> {
+  async function disposeChildSession(session: AgentSession, hasExtensions: boolean, workspace?: BtwSshWorkspace): Promise<void> {
     try {
       if (hasExtensions) {
         await session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" });
       }
     } finally {
-      session.dispose();
+      try {
+        session.dispose();
+      } finally {
+        await workspace?.dispose();
+      }
     }
   }
 
@@ -2032,6 +2128,13 @@ export default function (pi: ExtensionAPI) {
     }
 
     const builtinTools = BTW_TOOLS_BY_MODE[mode];
+    const workspaceMode = await readBtwWorkspaceMode({ cwd: ctx.cwd, agentDir, projectTrusted: ctx.isProjectTrusted() });
+    const workspace = workspaceMode === "ssh" ? await createBtwSshWorkspace(pi, ctx, mode === "readonly") : undefined;
+    const workspaceIdentity = workspace?.identity ?? `local:${ctx.cwd}`;
+    if (pendingThread.some((entry) => (entry.workspaceIdentity ?? `local:${ctx.cwd}`) !== workspaceIdentity)) {
+      await workspace?.dispose();
+      throw new Error("BTW workspace differs from its saved thread. Run /btw:clear before continuing.");
+    }
     let childSession: AgentSession | undefined;
     const sessionOptions: CreateAgentSessionOptions = {
       cwd: ctx.cwd,
@@ -2039,14 +2142,22 @@ export default function (pi: ExtensionAPI) {
       model: settings.model,
       ...modelRuntimeOptions,
       thinkingLevel: settings.thinkingLevel,
+      ...(workspace ? { customTools: workspace.tools } : {}),
       // 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,
+        ctx, () => childSession?.getActiveToolNames() ?? builtinTools, [BTW_SYSTEM_PROMPT], extensionResources, workspace?.label,
       ),
     };
-    const { session, extensionsResult } = await createAgentSession(sessionOptions);
+    let created: Awaited<ReturnType<typeof createAgentSession>>;
+    try {
+      created = await createAgentSession(sessionOptions);
+    } catch (error) {
+      await workspace?.dispose();
+      throw error;
+    }
+    const { session, extensionsResult } = created;
     childSession = session;
     const hasExtensions = !!extensionResources;
     if (hasExtensions) {
@@ -2084,13 +2195,13 @@ export default function (pi: ExtensionAPI) {
         try {
           await session.abort();
         } finally {
-          await disposeChildSession(session, true);
+          await disposeChildSession(session, true, workspace);
         }
         throw error;
       }
     }
 
-    return { session, mode, subscriptions: new Set(), sideThreadStartIndex, promptQueue: Promise.resolve(), hasExtensions };
+    return { session, mode, subscriptions: new Set(), sideThreadStartIndex, promptQueue: Promise.resolve(), hasExtensions, workspace, workspaceIdentity };
   }
 
   function ensureBtwSession(ctx: ExtensionCommandContext, mode: BtwThreadMode): Promise<BtwSessionRuntime | null> {
@@ -2114,7 +2225,15 @@ export default function (pi: ExtensionAPI) {
     }
 
     if (activeBtwSession?.mode === mode) {
-      return activeBtwSession;
+      try {
+        activeBtwSession.workspace?.assertCurrent();
+        return activeBtwSession;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        setOverlayStatus(message, ctx);
+        notify(ctx, message, "error");
+        return null;
+      }
     }
 
     await disposeBtwSession();
@@ -2123,7 +2242,7 @@ export default function (pi: ExtensionAPI) {
       const created = await createBtwSubSession(ctx, mode, settings);
       if (generation !== btwLifecycleGeneration) {
         await requestBtwSessionAbort(created);
-        await disposeChildSession(created.session, created.hasExtensions);
+        await disposeChildSession(created.session, created.hasExtensions, created.workspace);
         return null;
       }
       activeBtwSession = created;
@@ -2195,6 +2314,7 @@ export default function (pi: ExtensionAPI) {
             () => {
               void toggleOverlayWidth(ctx);
             },
+            () => activeBtwSession?.workspace?.label ?? "local",
           );
 
           overlay.focused = runtime.handle?.isFocused() ?? true;
@@ -2441,13 +2561,13 @@ export default function (pi: ExtensionAPI) {
 
   function parseOverlayBtwCommand(value: string): { name: string; args: string } | null {
     const trimmed = value.trim();
-    const match = trimmed.match(/^\/(btw:(?:new|ask|tangent|clear|inject|summarize|model|thinking))(?:\s+(.*))?$/);
-    if (!match) {
+    const match = trimmed.match(/^\/(\S+)(?:\s+([\s\S]*))?$/);
+    if (!match || !BTW_COMMANDS.some((command) => command.name === match[1])) {
       return null;
     }
 
     return {
-      name: match[1],
+      name: match[1] === "side" ? "btw" : match[1],
       args: match[2]?.trim() ?? "",
     };
   }
@@ -2669,6 +2789,7 @@ export default function (pi: ExtensionAPI) {
     await ensureOverlay(ctx);
 
     try {
+      sessionRuntime.workspace?.assertCurrent();
       await session.prompt(question, { source: "extension" });
       if (!isCurrentGeneration()) {
         return;
@@ -2704,6 +2825,7 @@ export default function (pi: ExtensionAPI) {
         thinkingLevel,
         timestamp: Date.now(),
         usage: response.usage,
+        workspaceIdentity: sessionRuntime.workspaceIdentity,
       };
 
       pendingThread.push(details);
@@ -2913,73 +3035,13 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
-  pi.registerCommand("btw", {
-    description: "Continue a side conversation in a focused BTW modal. Add --save to also persist a visible note.",
-    handler: async (args, ctx) => {
-      await dispatchBtwCommand("btw", args, ctx);
-    },
-  });
-
-  pi.registerCommand("side", {
-    description: "Alias for /btw: continue a side conversation in a focused BTW modal.",
-    handler: async (args, ctx) => {
-      await dispatchBtwCommand("btw", args, ctx);
-    },
-  });
-
-  pi.registerCommand("btw:tangent", {
-    description: "Start or continue a contextless BTW tangent in the focused BTW modal.",
-    handler: async (args, ctx) => {
-      await dispatchBtwCommand("btw:tangent", args, ctx);
-    },
-  });
-
-  pi.registerCommand("btw:ask", {
-    description: "Ask a read-only side question: inherits main-session context but exposes only read/grep/find/ls tools.",
-    handler: async (args, ctx) => {
-      await dispatchBtwCommand("btw:ask", args, ctx);
-    },
-  });
-
-  pi.registerCommand("btw:new", {
-    description: "Start a fresh BTW thread with main-session context. Optionally ask the first question immediately.",
-    handler: async (args, ctx) => {
-      await dispatchBtwCommand("btw:new", args, ctx);
-    },
-  });
-
-  pi.registerCommand("btw:clear", {
-    description: "Dismiss the BTW modal/widget and clear the current thread.",
-    handler: async (args, ctx) => {
-      await dispatchBtwCommand("btw:clear", args, ctx);
-    },
-  });
-
-  pi.registerCommand("btw:inject", {
-    description: "Inject the full BTW thread into the main agent as a user message.",
-    handler: async (args, ctx) => {
-      await dispatchBtwCommand("btw:inject", args, ctx);
-    },
-  });
-
-  pi.registerCommand("btw:summarize", {
-    description: "Summarize the BTW thread, then inject the summary into the main agent.",
-    handler: async (args, ctx) => {
-      await dispatchBtwCommand("btw:summarize", args, ctx);
-    },
-  });
-
-  pi.registerCommand("btw:model", {
-    description: "Show, set, or clear the BTW-only model override.",
-    handler: async (args, ctx) => {
-      await dispatchBtwCommand("btw:model", args, ctx);
-    },
-  });
+  for (const command of BTW_COMMANDS) {
+    pi.registerCommand(command.name, {
+      description: command.description,
+      handler: async (args, ctx) => {
+        await dispatchBtwCommand(command.name === "side" ? "btw" : command.name, args, ctx);
+      },
+    });
+  }
 
-  pi.registerCommand("btw:thinking", {
-    description: "Show, set, or clear the BTW-only thinking override.",
-    handler: async (args, ctx) => {
-      await dispatchBtwCommand("btw:thinking", args, ctx);
-    },
-  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-btw",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "A pi extension for parallel side conversations with /btw",
   "type": "module",
   "license": "MIT",