@maxiaochao/pi-toolkit 0.10.7 → 0.10.8

package/packages/worktree/extensions/worktree.ts

@@ -0,0 +1,173 @@
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+import { unlinkSync } from "node:fs";
+import { SessionManager, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+const CLI_PATH = fileURLToPath(new URL("../bin/pi-worktree", import.meta.url));
+
+export const WORKTREE_SWITCH_REQUEST = "pi-worktree/switch-request";
+
+export interface WorktreePrepareResult {
+  status: "created" | "attached" | "reused" | "already-active";
+  path: string;
+  branch: string;
+  dirty: boolean;
+}
+
+export interface WorktreeSwitchRequest extends WorktreePrepareResult {
+  kind: typeof WORKTREE_SWITCH_REQUEST;
+  version: 1;
+  action: "fork-and-switch";
+  sessionFile: string;
+}
+
+const SwitchRequestSchema = Type.Object({
+  kind: Type.Literal(WORKTREE_SWITCH_REQUEST),
+  version: Type.Literal(1),
+  action: Type.Literal("fork-and-switch"),
+  sessionFile: Type.String(),
+  status: Type.Union([
+    Type.Literal("created"),
+    Type.Literal("attached"),
+    Type.Literal("reused"),
+    Type.Literal("already-active"),
+  ]),
+  path: Type.String(),
+  branch: Type.String(),
+  dirty: Type.Boolean(),
+});
+
+function parseCommandArgs(input: string): { name: string; base?: string } {
+  const tokens = input.trim().split(/\s+/).filter(Boolean);
+  if (tokens[0] !== "start" || tokens.length < 2) {
+    throw new Error("用法：/worktree start <name> [--base <ref>]");
+  }
+
+  const name = tokens[1];
+  let base: string | undefined;
+  for (let index = 2; index < tokens.length; index += 1) {
+    if (tokens[index] !== "--base" || !tokens[index + 1] || base !== undefined) {
+      throw new Error("用法：/worktree start <name> [--base <ref>]");
+    }
+    base = tokens[index + 1];
+    index += 1;
+  }
+  return { name, base };
+}
+
+function parsePrepareOutput(stdout: string): WorktreePrepareResult {
+  const line = stdout.trim().split("\n").filter(Boolean).at(-1);
+  if (!line) throw new Error("pi-worktree prepare 没有返回结果");
+  const result = JSON.parse(line) as Partial<WorktreePrepareResult>;
+  if (
+    !["created", "attached", "reused", "already-active"].includes(String(result.status))
+    || typeof result.path !== "string"
+    || typeof result.branch !== "string"
+    || typeof result.dirty !== "boolean"
+  ) {
+    throw new Error("pi-worktree prepare 返回了无效结果");
+  }
+  return result as WorktreePrepareResult;
+}
+
+async function prepareWorktree(
+  pi: ExtensionAPI,
+  cwd: string,
+  name: string,
+  base?: string,
+): Promise<WorktreePrepareResult> {
+  const args = ["prepare", "--json"];
+  if (base) args.push("--base", base);
+  args.push(name);
+  const result = await pi.exec(CLI_PATH, args, { cwd });
+  if (result.code !== 0) {
+    throw new Error(result.stderr.trim() || result.stdout.trim() || `pi-worktree prepare 失败（退出码 ${result.code}）`);
+  }
+  return parsePrepareOutput(result.stdout);
+}
+
+export default function worktreeExtension(pi: ExtensionAPI) {
+  pi.registerCommand("worktree", {
+    description: "创建或复用 worktree，并在当前界面切换过去",
+    handler: async (input, ctx) => {
+      let prepared: WorktreePrepareResult;
+      let targetSessionFile: string;
+      try {
+        const { name, base } = parseCommandArgs(input);
+        const sourceSessionFile = ctx.sessionManager.getSessionFile();
+        if (!sourceSessionFile) {
+          throw new Error("当前是临时会话；请启用 session 持久化后再切换 worktree");
+        }
+
+        await ctx.waitForIdle();
+        prepared = await prepareWorktree(pi, ctx.cwd, name, base);
+        if (resolve(ctx.cwd) === resolve(prepared.path)) {
+          ctx.ui.notify(`已经位于 worktree：${prepared.path}`, "info");
+          return;
+        }
+
+        const target = SessionManager.forkFrom(sourceSessionFile, prepared.path);
+        targetSessionFile = target.getSessionFile() ?? "";
+        if (!targetSessionFile) throw new Error("无法为 worktree 创建持久会话");
+      } catch (error) {
+        ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+        return;
+      }
+
+      // Do not catch replacement errors here: switchSession may already have
+      // invalidated this command context, so Pi must report such failures.
+      const switched = await ctx.switchSession(targetSessionFile, {
+        withSession: async (next) => {
+          const dirtyNote = prepared.dirty ? "（已有未提交改动）" : "";
+          next.ui.notify(`已切换到 ${prepared.branch}：${prepared.path}${dirtyNote}`, "success");
+        },
+      });
+      if (switched.cancelled) {
+        try {
+          unlinkSync(targetSessionFile);
+        } catch (error) {
+          ctx.ui.notify(`worktree 会话切换已取消，但无法清理派生会话：${error instanceof Error ? error.message : String(error)}`, "warning");
+          return;
+        }
+        ctx.ui.notify("worktree 会话切换已取消", "warning");
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "enter_worktree",
+    label: "Enter Worktree",
+    exposure: "model-only",
+    description:
+      "Create or reuse an isolated git worktree and request that the host Harness move this current conversation into it. Call this tool alone, then stop; the Harness performs the session switch after the tool completes.",
+    parameters: Type.Object({
+      name: Type.String({ description: "Single-segment worktree and branch name" }),
+      base: Type.Optional(Type.String({ description: "Optional git ref used only when creating a new branch" })),
+    }),
+    outputSchema: SwitchRequestSchema,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const sourceSessionFile = ctx.sessionManager.getSessionFile();
+      if (!sourceSessionFile) throw new Error("当前是临时会话，Harness 无法续接到 worktree");
+
+      const prepared = await prepareWorktree(pi, ctx.cwd, params.name, params.base);
+      const request: WorktreeSwitchRequest = {
+        kind: WORKTREE_SWITCH_REQUEST,
+        version: 1,
+        action: "fork-and-switch",
+        sessionFile: sourceSessionFile,
+        ...prepared,
+      };
+      const dirtyNote = prepared.dirty ? " 目标 worktree 已有未提交改动。" : "";
+      return {
+        content: [{
+          type: "text",
+          text: `Worktree ${prepared.status}: ${prepared.path}.${dirtyNote} 已请求 Harness 将当前会话切换到该目录；不要继续调用仓库工具。`,
+        }],
+        details: request,
+        structuredContent: request,
+        terminate: true,
+      };
+    },
+  });
+}

package/packages/worktree/package.json

@@ -1,20 +1,49 @@
 {
   "name": "@maxiaochao/pi-worktree",
-  "version": "0.1.0",
-  "description": "Git worktree CLI and Pi skill for isolated coding tasks.",
+  "version": "0.2.0",
+  "description": "Git worktree CLI, Pi extension, and skill for isolated coding tasks.",
   "type": "module",
-  "keywords": ["pi-package", "pi-skill", "git", "worktree"],
-  "files": ["bin", "skills", "scripts", "docs", "README.md", "TESTING.md", "CHANGELOG.md"],
+  "keywords": [
+    "pi-package",
+    "pi-skill",
+    "git",
+    "worktree"
+  ],
+  "files": [
+    "bin",
+    "extensions",
+    "skills",
+    "scripts",
+    "docs",
+    "README.md",
+    "TESTING.md",
+    "CHANGELOG.md"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/chaochaoxiaochao/pi-toolkit.git",
     "directory": "packages/worktree"
   },
-  "bin": { "pi-worktree": "bin/pi-worktree" },
-  "pi": { "skills": ["./skills"] },
+  "bin": {
+    "pi-worktree": "bin/pi-worktree"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/worktree.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
   "scripts": {
-    "test": "node --test tests/install.test.mjs && bash tests/run-tests.sh",
+    "test": "node --test tests/install.test.mjs && node --experimental-strip-types --test tests/extension.test.mjs && bash tests/run-tests.sh",
     "postinstall": "node scripts/install.mjs"
   },
-  "publishConfig": { "access": "public" }
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/packages/worktree/skills/pi-worktree/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: pi-worktree
-description: Create, inspect, and clean up git worktrees with the pi-worktree CLI (start/list/info/remove/prune), which also launches Pi inside the worktree. Use when a task warrants isolation in its own worktree, or when the user asks to handle something the worktree way.
+description: Create, enter, inspect, and clean up git worktrees through the enter_worktree tool, /worktree command, or pi-worktree CLI. Use when a task warrants isolation in its own worktree, or when the user asks to handle something the worktree way.
 ---
 
 # pi-worktree
 
-`pi-worktree` wraps git worktree creation and Pi launch into one command. Worktrees live in `.worktrees/<name>` (added to `.gitignore`), each with a branch of the same name, branched from the branch you are on now (or `HEAD` when detached). The base commit is recorded in `branch.<name>.base` / `branch.<name>.baseRef` so `info` can always report where the branch came from.
+Worktrees live in `.worktrees/<name>` (added to `.gitignore`), each with a branch of the same name, branched from the current branch (or `HEAD` when detached). The base commit is recorded in `branch.<name>.base` / `branch.<name>.baseRef` so `info` can report where the branch came from.
 
 Installed by the package postinstall hook to `~/.local/bin/pi-worktree`, with bash completion for subcommands and existing worktree names.
 
@@ -13,6 +13,9 @@ Installed by the package postinstall hook to `~/.local/bin/pi-worktree`, with ba
 
 | Command | Effect |
 |---|---|
+| `enter_worktree({ name, base? })` | Agent entrypoint: create/reuse a worktree and ask a compatible Harness to move this conversation there. Call it alone and stop after it returns. |
+| `/worktree start <name> [--base <ref>]` | User entrypoint: fork the current persistent session into the worktree and switch the current Pi UI. |
+| `pi-worktree prepare [--base <ref>] [--json] <name>` | Create/reuse without launching Pi; `--json` is the machine interface. |
 | `pi-worktree start <name> [pi args...]` | Create or reuse `.worktrees/<name>`, then launch Pi inside it. Already inside a linked worktree, it just launches Pi there. |
 | `pi-worktree start --base <ref> <name> [pi args...]` | Same, but branch from `<ref>` instead of the current branch. |
 | `pi-worktree list` | All worktrees; the main checkout is marked `(main checkout)`, stale registrations are flagged. |
@@ -24,13 +27,15 @@ Installed by the package postinstall hook to `~/.local/bin/pi-worktree`, with ba
 ## Isolating a task
 
 1. **Survey** — `pi-worktree list`, plus `pi-worktree info <name>` when the name you want is already taken. Reuse is free; a removed worktree is gone for good, because `remove` deletes its branch.
-2. **Start** — `pi-worktree start <name>` (with `--base <ref>` when the work must not start from the current branch). Done when `list` shows the new worktree on its own branch.
+2. **Enter** — as an Agent, call `enter_worktree` once and stop so the Harness can switch after settlement. A user can instead run `/worktree start <name>`. Use the CLI `start` only when a separate Pi process is wanted.
 3. **Work** — inside the worktree: commit there, and check `pi-worktree info <name>` before claiming progress. `ahead: N commits since base` is the evidence.
 4. **Land** — `pi-worktree out`, then `git merge <name>` in the main checkout. Done when the worktree's unique commits are in the target branch.
 5. **Clean up** — `pi-worktree remove <name>`. A merged branch goes without prompting; anything unmerged asks once.
 
-## Driving it from an agent
+## Entry-point rules
 
-- `start` **execs `pi`** in the worktree, and `out` execs a shell. With no trailing Pi args both want an interactive terminal, so either run `start <name> -p "<task>"` for a headless nested run, or hand the bare `start <name>` to the user to run themselves.
+- Prefer `enter_worktree` when it is available. Its `fork-and-switch` request requires Harness support: after `agent_settled`, the host forks the source session into the target cwd and switches to that persisted session. After the tool returns, do not read or modify repository files until the host has switched cwd.
+- `/worktree` is user-facing and cannot be invoked by the model. It requires a persisted session because it forks history into a session whose header owns the worktree cwd.
+- `pi-worktree start` **execs a new `pi`** in the worktree, and `out` execs a shell. Use this only for an intentionally separate process/session.
+- `prepare` is idempotent. It reports whether the target was created, attached, reused, or already active, and reports dirty reuse rather than discarding anything.
 - `remove` asks before discarding dirty files or unmerged commits, and a non-interactive stdin (EOF) aborts safely. Answer explicitly when the removal is intended: `printf 'y\ny\n' | pi-worktree remove <name>`.
-- Your own working directory cannot change. "Isolate this in a worktree" therefore means launching a nested headless Pi in the worktree, or telling the user to run `pi-worktree start <name>`.

package/packages/worktree/tests/extension.test.mjs

@@ -0,0 +1,114 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+const root = await mkdtemp(join(tmpdir(), "pi-worktree-extension-"));
+process.env.PI_CODING_AGENT_DIR = join(root, "agent");
+const { default: register, WORKTREE_SWITCH_REQUEST } = await import("../extensions/worktree.ts");
+
+test.after(async () => {
+  await rm(root, { recursive: true, force: true });
+});
+
+function setup(prepared) {
+  const commands = new Map();
+  const tools = new Map();
+  const pi = {
+    registerCommand(name, definition) { commands.set(name, definition); },
+    registerTool(definition) { tools.set(definition.name, definition); },
+    async exec(command, args, options) {
+      assert.match(command, /packages\/worktree\/bin\/pi-worktree$/);
+      assert.deepEqual(args, ["prepare", "--json", "--base", "main", "feature"]);
+      assert.equal(options.cwd, prepared.cwd);
+      return { code: 0, stdout: `${JSON.stringify(prepared.result)}\n`, stderr: "" };
+    },
+  };
+  register(pi);
+  return { commands, tools };
+}
+
+test("registers /worktree and switches a forked persistent session", async () => {
+  const cwd = join(root, "main");
+  const target = join(root, "main", ".worktrees", "feature");
+  await mkdir(target, { recursive: true });
+  const sourceSession = join(root, "source.jsonl");
+  await writeFile(sourceSession, `${JSON.stringify({ type: "session", version: 3, id: "source", timestamp: new Date().toISOString(), cwd })}\n`);
+  const prepared = { cwd, result: { status: "created", path: target, branch: "feature", dirty: false } };
+  const { commands } = setup(prepared);
+  const notifications = [];
+  let switchedFile;
+  await commands.get("worktree").handler("start feature --base main", {
+    cwd,
+    sessionManager: { getSessionFile: () => sourceSession },
+    waitForIdle: async () => {},
+    ui: { notify: (...args) => notifications.push(args) },
+    async switchSession(file, options) {
+      switchedFile = file;
+      await options.withSession({ ui: { notify: (...args) => notifications.push(args) } });
+      return { cancelled: false };
+    },
+  });
+
+  const header = JSON.parse((await readFile(switchedFile, "utf8")).split("\n")[0]);
+  assert.equal(header.cwd, target);
+  assert.equal(header.parentSession, sourceSession);
+  assert.deepEqual(notifications.at(-1), [`已切换到 feature：${target}`, "success"]);
+});
+
+test("removes the forked session when /worktree switching is cancelled", async () => {
+  const cwd = join(root, "cancel-main");
+  const target = join(cwd, ".worktrees", "feature");
+  await mkdir(target, { recursive: true });
+  const sourceSession = join(root, "cancel-source.jsonl");
+  await writeFile(sourceSession, `${JSON.stringify({ type: "session", version: 3, id: "cancel-source", timestamp: new Date().toISOString(), cwd })}\n`);
+  const prepared = { cwd, result: { status: "created", path: target, branch: "feature", dirty: false } };
+  const { commands } = setup(prepared);
+  const notifications = [];
+  let forkedFile;
+  await commands.get("worktree").handler("start feature --base main", {
+    cwd,
+    sessionManager: { getSessionFile: () => sourceSession },
+    waitForIdle: async () => {},
+    ui: { notify: (...args) => notifications.push(args) },
+    async switchSession(file) {
+      forkedFile = file;
+      return { cancelled: true };
+    },
+  });
+
+  await assert.rejects(readFile(forkedFile, "utf8"), { code: "ENOENT" });
+  assert.deepEqual(notifications.at(-1), ["worktree 会话切换已取消", "warning"]);
+});
+
+test("registers enter_worktree with a durable Harness switch request", async () => {
+  const cwd = join(root, "main");
+  const target = join(cwd, ".worktrees", "feature");
+  const sourceSession = join(root, "tool-source.jsonl");
+  const prepared = { cwd, result: { status: "reused", path: target, branch: "feature", dirty: true } };
+  const { tools } = setup(prepared);
+  const tool = tools.get("enter_worktree");
+  assert.equal(tool.exposure, "model-only");
+  assert.ok(tool.outputSchema);
+  const result = await tool.execute(
+    "call-1",
+    { name: "feature", base: "main" },
+    new AbortController().signal,
+    undefined,
+    { cwd, sessionManager: { getSessionFile: () => sourceSession } },
+  );
+
+  assert.equal(result.terminate, true);
+  assert.deepEqual(result.details, {
+    kind: WORKTREE_SWITCH_REQUEST,
+    version: 1,
+    action: "fork-and-switch",
+    sessionFile: sourceSession,
+    status: "reused",
+    path: target,
+    branch: "feature",
+    dirty: true,
+  });
+  assert.deepEqual(result.structuredContent, result.details);
+});

package/packages/worktree/tests/run-tests.sh

@@ -42,5 +42,91 @@ grep -q 'status:   clean' "$ROOT/info.txt"
 grep -q 'branch:   feature' "$ROOT/info.txt"
 grep -q 'based on:' "$ROOT/info.txt"
 
+bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json feature > "$ROOT/reused.json"
+node -e '
+  const fs = require("node:fs");
+  const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+  if (value.status !== "reused" || value.branch !== "feature" || value.dirty !== false) process.exit(1);
+' "$ROOT/reused.json"
+
+bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json prepared > "$ROOT/created.json"
+node -e '
+  const fs = require("node:fs");
+  const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+  if (value.status !== "created" || value.branch !== "prepared" || !value.path.endsWith("/.worktrees/prepared")) process.exit(1);
+' "$ROOT/created.json"
+
+mkdir -p nested/path
+(cd nested/path && bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json from-subdir) > "$ROOT/subdir.json"
+node -e '
+  const fs = require("node:fs");
+  const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+  if (value.path !== process.argv[2] + "/.worktrees/from-subdir") process.exit(1);
+' "$ROOT/subdir.json" "$ROOT/repo"
+
+git branch attachable
+bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json attachable > "$ROOT/attached.json"
+node -e '
+  const fs = require("node:fs");
+  const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+  if (value.status !== "attached" || value.branch !== "attachable") process.exit(1);
+' "$ROOT/attached.json"
+
+bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json stale > /dev/null
+rm -rf .worktrees/stale
+if bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json stale >/dev/null 2>&1; then
+  echo "prepare silently replaced a stale worktree registration" >&2
+  exit 1
+fi
+git worktree prune
+
+git worktree add .worktrees/wrong -b another-branch >/dev/null
+if bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json wrong >/dev/null 2>&1; then
+  echo "prepare reused a path checked out on the wrong branch" >&2
+  exit 1
+fi
+
+mkdir .worktrees/main
+if bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json main >/dev/null 2>&1; then
+  echo "prepare reused an ordinary directory as a worktree"
+  exit 1
+fi
+
+printf 'changed\n' >> .worktrees/prepared/tracked.txt
+bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json prepared > "$ROOT/dirty.json"
+node -e '
+  const fs = require("node:fs");
+  const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+  if (value.status !== "reused" || value.dirty !== true) process.exit(1);
+' "$ROOT/dirty.json"
+
+(cd .worktrees/prepared && bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json prepared) > "$ROOT/active.json"
+node -e '
+  const fs = require("node:fs");
+  const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+  if (value.status !== "already-active" || value.dirty !== true) process.exit(1);
+' "$ROOT/active.json"
+
+if bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json ../escape >/dev/null 2>&1; then
+  echo "prepare accepted an unsafe worktree name" >&2
+  exit 1
+fi
+
+mkdir "$ROOT/symlink-repo" "$ROOT/outside-worktrees"
+(
+  cd "$ROOT/symlink-repo"
+  git init -q -b main
+  git config user.email test@example.com
+  git config user.name Test
+  printf 'base\n' > tracked.txt
+  git add tracked.txt
+  git commit -qm initial
+  ln -s "$ROOT/outside-worktrees" .worktrees
+  if bash "$PACKAGE_DIR/bin/pi-worktree" prepare --json escaped >/dev/null 2>&1; then
+    echo "prepare followed a symlinked .worktrees directory" >&2
+    exit 1
+  fi
+)
+
 bash "$PACKAGE_DIR/bin/pi-worktree" --help | grep -q 'pi-worktree start'
 printf 'PASS worktree CLI integration cases\n'