pi-petrroll 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Petr Houška
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# pi-petrroll
+
+Small, focused extensions for [Pi](https://pi.dev). MIT licensed.
+
+| Extension | Command | Agent tool |
+| --- | --- | --- |
+| [Change directory](#change-directory) | `/cd <path>` | `change_directory` |
+
+One extension, one command, one tool. No skills, shell wrappers, or replacement built-in tools.
+
+## Install
+
+Requires **interactive Pi 0.85.1 or newer** (`@earendil-works/pi-coding-agent`); tested against 0.85.1. Earlier Pi versions may not rebuild cwd-bound services when switching sessions.
+
+```sh
+pi install npm:pi-petrroll
+```
+
+Or install directly from GitHub:
+
+```sh
+pi install git:github.com/petrroll/pi-petrroll
+```
+
+Run `/reload` in an existing Pi session, or start Pi. Install globally (the default), so the extension remains available when switching projects.
+
+For local development, use this checkout instead of the npm or GitHub install:
+
+```sh
+pi install /absolute/path/to/pi-petrroll
+```
+
+Choose one installation source, not both. Use `pi config` to enable/disable individual extensions as this collection grows.
+
+## Change directory
+
+### Let the agent do it
+
+For example, start Pi in `~/projects` and ask:
+
+> Create a worktree of pi-mono for issue #123, switch this session into it, and fix the issue there.
+
+The agent uses ordinary `bash`/Git to create the worktree, then calls:
+
+```json
+{ "path": "~/projects/pi-issue-123" }
+```
+
+with the `change_directory` tool. Once the current run settles, Pi copies the conversation into the worktree's session storage, switches to that session, and automatically continues the task there.
+
+No quit, terminal `cd`, restart, or cross-directory session-copy confirmation. **Normal Pi project-trust prompts and other extensions' session-switch guards still apply.** This extension does not automatically trust destination code.
+
+### Change it yourself
+
+```text
+/cd ~/projects/pi-issue-123
+/cd ../another-worktree
+/cd /home/me/projects/a folder with spaces
+/cd "../a folder with spaces"
+```
+
+Bare `/cd` shows the current directory and usage. Relative paths use Pi's current cwd. `~`, `~/…`, single-quoted paths, JSON double-quoted paths, and symlinks are supported. Paths are not shell commands: no variable expansion, globbing, `~username`, or `cd -`.
+
+Manual `/cd` switches without starting another model response; the agent tool resumes automatically. An existing destination is required. The extension does not create directories or worktrees itself.
+
+### What changes
+
+- A new session ID and session file are created for the destination, using Pi's `SessionManager.forkFrom()`.
+- The original session is left in place. The full conversation tree is copied, and the currently selected branch is preserved.
+- Pi's native session replacement rebuilds built-in tools, the working-directory display, settings, extensions, skills, and project context such as `AGENTS.md` for the destination.
+- `pi -c` from the destination can continue the copied session. Copies use Pi's normal per-directory session storage (respecting `PI_CODING_AGENT_DIR`), not a source session's explicit `--session-dir` or `PI_CODING_AGENT_SESSION_DIR` override. If you use those overrides, resume the copy by its file path or remove the override.
+- No `process.chdir()` trick, built-in tool overrides, or Pi internals are patched. Your parent terminal's working directory does **not** change.
+
+### Safety and limitations
+
+- Interactive/TUI mode only. Print, JSON, RPC, and `--no-session` are deliberately unsupported in this first version.
+- Linux is tested locally and in Ubuntu CI. Windows is expected to work but has not been verified. For manual commands on Windows, prefer `/cd "C:/Users/you/worktree with spaces"`; double-quoted backslashes are interpreted as JSON escapes. Use `~/path`, not `~\path`. The agent tool handles quoting automatically.
+- Pi's session cwd changes, but Node's `process.cwd()` does not. Third-party extensions that use process-relative filesystem paths or spawn commands without an explicit cwd may still operate in the original directory. Pi's built-in tools and `pi.exec()` use the rebuilt session/extension cwd.
+- Switching does not recreate shell environment changes such as `direnv` or virtualenv activation, and does not move already-running background processes.
+- The session must already be saved. In a brand-new session, send a message first.
+- The agent should call `change_directory` **alone**, after worktree creation has completed. The tool requests early termination and the command waits for idle so completed tool results are included in the copy. If mixed with other tools, those calls still run in the **old** directory; the switch waits until the run settles.
+- Explicitly aborting a pending tool handoff prevents the switch. Invalid paths and concurrent requests are rejected.
+- A cancelled session switch removes the unused copy and keeps the original session. If Pi fails while rebuilding the replacement runtime, its normal fatal-error handling applies; the original and any created copy remain available for recovery.
+- The copied history can contain references to the old project. A visible context message records the change, and the new system prompt contains the destination's instructions.
+- Switching reloads project extensions according to Pi's trust policy. Install only code you trust.
+
+## Development
+
+```sh
+npm ci --ignore-scripts
+npm run check
+npm test
+```
+
+Tests cover path handling, copy/branch preservation, cancellation, aborts, concurrency, and a real Pi runtime handoff with a fake model stream. The runtime test verifies that tool results are copied, `read` and `bash` use the new cwd, destination `AGENTS.md` replaces source context, and the agent continues. Tests do not call a model API or use your credentials.
+
+```text
+extensions/
+  cd/
+    index.ts
+  # Add another-extension/index.ts here.
+tests/
+  cd.test.ts
+  runtime.test.ts
+```
+
+Pi discovers entry points through `pi.extensions` in `package.json`. Add future independent extensions under `extensions/<name>/index.ts`; no new skill or package is needed. Keep helpers inside the extension directory so they are not discovered as standalone extensions.
+
+## License
+
+[MIT](LICENSE) © 2026 Petr Houška.

package/extensions/cd/index.ts

@@ -0,0 +1,148 @@
+import { existsSync, realpathSync, statSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import {
+  SessionManager,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+/** The entire argument is a path, not a shell expression. */
+export function resolveDirectory(argument: string, cwd: string): string {
+  let path = argument.trim();
+  if (path.startsWith('"')) {
+    path = JSON.parse(path) as string;
+    if (typeof path !== "string") throw new Error("Expected a directory path.");
+  } else if (path.startsWith("'") && path.endsWith("'")) {
+    path = path.slice(1, -1);
+  }
+  if (!path || /[\x00-\x1f\x7f]/.test(path)) {
+    throw new Error("Provide a non-empty directory path without control characters.");
+  }
+  if (path.startsWith("@")) path = path.slice(1);
+  if (path === "~") path = homedir();
+  else if (path.startsWith("~/")) path = resolve(homedir(), path.slice(2));
+  else if (path.startsWith("~")) throw new Error("Use ~ or ~/path, not ~username.");
+  const target = realpathSync(resolve(cwd, path));
+  if (!statSync(target).isDirectory()) throw new Error(`Not a directory: ${target}`);
+  return target;
+}
+
+function requireSavedSession(ctx: ExtensionContext): string {
+  // Interactive mode owns the asynchronous command handoff and runtime rebinding.
+  if (ctx.mode !== "tui") throw new Error("Changing directory currently requires interactive Pi.");
+  const file = ctx.sessionManager.getSessionFile();
+  if (!file || !existsSync(file)) {
+    throw new Error("This session is not saved yet. Send a message first; --no-session is not supported.");
+  }
+  return file;
+}
+
+export default function cdExtension(pi: ExtensionAPI) {
+  let busy = false;
+  let toolRequest: { argument: string; signal: AbortSignal | undefined } | undefined;
+
+  pi.registerCommand("cd", {
+    description: "Copy this session into another directory and switch there: /cd <path>",
+    handler: async (args, ctx) => {
+      const request = toolRequest?.argument === args ? toolRequest : undefined;
+      if (request) toolRequest = undefined;
+      if (busy) throw new Error("A directory change is already pending.");
+      if (!args.trim()) {
+        ctx.ui.notify(`Current directory: ${ctx.cwd}\nUsage: /cd <path>`, "info");
+        return;
+      }
+      busy = true;
+      try {
+        // Commands dispatch immediately, even with deliverAs: followUp. Waiting
+        // here (never inside tool.execute) lets all tool results reach disk first.
+        await ctx.waitForIdle();
+        request?.signal?.throwIfAborted();
+        const source = requireSavedSession(ctx);
+        const target = resolveDirectory(args, ctx.cwd);
+        if (target === realpathSync(ctx.cwd)) {
+          ctx.ui.notify(`Already in ${target}`, "info");
+          return;
+        }
+
+        const copy = SessionManager.forkFrom(source, target);
+        // forkFrom copies the whole tree but opens its last entry. Preserve the
+        // actual selected leaf, including when the user navigated with /tree.
+        const leaf = ctx.sessionManager.getLeafId();
+        if (leaf) copy.branch(leaf);
+        else copy.resetLeaf();
+        copy.appendCustomMessageEntry(
+          "pi-petrroll:cd",
+          `Working directory changed from ${ctx.cwd} to ${target}. ` +
+            "Relative paths now refer to the new directory. Follow the newly loaded project instructions.",
+          true,
+          { from: ctx.cwd, to: target, parentSession: source },
+        );
+        const destination = copy.getSessionFile()!;
+        // Do not use captured pi/ctx in withSession: the old runtime is invalid.
+        const result = await ctx.switchSession(destination, {
+          withSession: async (fresh) => {
+            fresh.ui.notify(`Changed directory to ${fresh.cwd}`, "info");
+            if (request) {
+              await fresh.sendUserMessage(
+                "The requested directory change has completed. Continue the outstanding task in this directory. " +
+                  "If no work remains, briefly confirm the change.",
+              );
+            }
+          },
+        });
+        if (result.cancelled) {
+          unlinkSync(destination);
+          pi.sendMessage({
+            customType: "pi-petrroll:cd",
+            content: "Directory change cancelled. The original session and working directory are unchanged.",
+            display: true,
+          });
+          ctx.ui.notify("Directory change cancelled.", "warning");
+        }
+      } finally {
+        // Local state only; session-bound pi/ctx may now be stale.
+        busy = false;
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "change_directory",
+    label: "Change directory",
+    description:
+      "Copy the current saved session into an existing directory and switch Pi there, reloading tools and project context. " +
+      "Interactive mode only. The switch happens after the current run settles, then work resumes automatically. " +
+      "Create any git worktree with bash first. Call this tool alone, not in parallel with other tools; do not do more work in the old directory afterward.",
+    promptSnippet: "Switch Pi to another project/worktree while keeping conversation history",
+    promptGuidelines: [
+      "Use change_directory to move Pi into a newly created worktree or another project; bash cd does not change Pi's working directory.",
+      "Call change_directory alone and let its handoff finish before doing further work.",
+    ],
+    parameters: Type.Object({
+      path: Type.String({ description: "Existing directory: absolute, relative to Pi's cwd, or ~/path" }),
+    }),
+    async execute(_id, { path }, signal, _onUpdate, ctx) {
+      signal?.throwIfAborted();
+      if (busy || toolRequest) throw new Error("A directory change is already pending.");
+      requireSavedSession(ctx);
+      const target = resolveDirectory(JSON.stringify(path), ctx.cwd);
+      if (target === realpathSync(ctx.cwd)) {
+        return { content: [{ type: "text", text: `Already in ${target}.` }], details: { cwd: target } };
+      }
+      const argument = JSON.stringify(target);
+      toolRequest = { argument, signal };
+      // Explicit expansion is essential: otherwise /cd is sent as text to the LLM.
+      pi.sendUserMessage(`/cd ${argument}`, { deliverAs: "followUp", expandPromptTemplates: true });
+      return {
+        content: [{
+          type: "text",
+          text: `Directory change to ${target} requested, not completed yet. End this run now; work will resume automatically after switching.`,
+        }],
+        details: { target, status: "pending" },
+        terminate: true,
+      };
+    },
+  });
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "pi-petrroll",
+  "version": "0.1.0",
+  "description": "Small, focused Pi extensions by petrroll: change projects without leaving your session.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Petr Houška (petrroll)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/petrroll/pi-petrroll.git"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "extensions",
+    "worktree"
+  ],
+  "files": [
+    "extensions",
+    "LICENSE",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "tsx --test tests/*.test.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.20.0",
+    "typebox": "^1.0.0",
+    "typescript": "^5.9.0"
+  }
+}