@henryqw/pi-herdr-clone 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Wang
+
+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,37 @@
+# `@henryqw/pi-herdr-clone`
+
+Pi extension that clones the current conversation path into a new Pi process in a new tab of the current Herdr workspace. Requires Pi Coding Agent 0.84.x (minimum 0.84.2) and a Pi session running inside Herdr.
+
+## Install
+
+```bash
+pi install npm:@henryqw/pi-herdr-clone
+```
+
+Remove with:
+
+```bash
+pi remove npm:@henryqw/pi-herdr-clone
+```
+
+## `/clone-tab`
+
+The command waits until Pi is idle, then:
+
+1. Validates the current Herdr pane and resolves its live workspace.
+2. Copies only the current Pi session path into a new persisted session file. Sibling branches are excluded and the original Pi session is not switched.
+3. Creates an unfocused Herdr tab in that workspace with the current working directory.
+4. Starts Pi in the tab's root pane with `--session <absolute-clone-file>`.
+5. Focuses the new tab after Pi starts successfully.
+
+The command requires `HERDR_ENV=1`, `HERDR_PANE_ID`, an existing persisted session file, and a current session leaf. It has no configuration or worktree behavior.
+
+If tab creation itself fails, the cloned session file is removed. If Herdr creates the tab but the response is incomplete, or once agent start is attempted, the tab and session file are retained because the launch outcome can be unknown; the error reports any known IDs for recovery. A later focus failure is shown as a warning and does not report the already-started clone as failed.
+
+## Development
+
+```bash
+npm test --workspace @henryqw/pi-herdr-clone
+npm run typecheck --workspace @henryqw/pi-herdr-clone
+npm run pack:check --workspace @henryqw/pi-herdr-clone
+```

package/extensions/clone-tab.ts

@@ -0,0 +1,135 @@
+import { randomUUID } from "node:crypto";
+import { stat, unlink } from "node:fs/promises";
+import { resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import {
+	SessionManager,
+	type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import { createHerdrClient, herdrCommandFailure, hasHerdrErrorCode } from "@henryqw/pi-herdr";
+
+const errorMessage = (error: unknown) => error instanceof Error ? error.message : String(error);
+
+function requiredString(value: unknown, label: string): string {
+	if (typeof value !== "string" || !value.trim()) throw new Error(`${label} is missing.`);
+	return value;
+}
+
+export default function herdrCloneExtension(pi: ExtensionAPI): void {
+	const herdr = createHerdrClient<{ cwd: string }>((command, args, options) =>
+		pi.exec(command, [...args], options));
+
+	pi.registerCommand("clone-tab", {
+		description: "Clone the current conversation path into a new Herdr tab",
+		handler: async (_args, ctx) => {
+			await ctx.waitForIdle();
+
+			if (process.env.HERDR_ENV !== "1") {
+				throw new Error("/clone-tab requires the current Pi session inside Herdr (HERDR_ENV=1).");
+			}
+			const requestedPaneId = requiredString(process.env.HERDR_PANE_ID, "HERDR_PANE_ID");
+			const currentSessionFile = requiredString(
+				ctx.sessionManager.getSessionFile(),
+				"Persisted Pi session file",
+			);
+			const leafId = requiredString(ctx.sessionManager.getLeafId(), "Current Pi session leaf");
+			const sessionFile = resolve(currentSessionFile);
+			let sourceStat;
+			try {
+				sourceStat = await stat(sessionFile);
+			} catch (error) {
+				throw new Error(`Persisted Pi session file does not exist: ${sessionFile}`, { cause: error });
+			}
+			if (!sourceStat.isFile()) throw new Error(`Persisted Pi session path is not a file: ${sessionFile}`);
+
+			const paneResponse = await herdr.json(["pane", "get", requestedPaneId], { cwd: ctx.cwd });
+			const pane = (paneResponse as { result?: { pane?: { pane_id?: unknown; workspace_id?: unknown } } }).result?.pane;
+			requiredString(pane?.pane_id, "Herdr pane response pane_id");
+			const workspaceId = requiredString(pane?.workspace_id, "Herdr pane response workspace_id");
+
+			const session = SessionManager.open(sessionFile, ctx.sessionManager.getSessionDir(), ctx.cwd);
+			const createdClone = session.createBranchedSession(leafId);
+			if (!createdClone) throw new Error("Pi did not create a persisted clone session file.");
+			const cloneFile = resolve(createdClone);
+			let cloneStat;
+			try {
+				cloneStat = await stat(cloneFile);
+			} catch (error) {
+				throw new Error(`Pi clone session file was not created: ${cloneFile}`, { cause: error });
+			}
+			if (!cloneStat.isFile()) throw new Error(`Pi clone session path is not a file: ${cloneFile}`);
+
+			const tabCreateArgs = ["tab", "create", "--workspace", workspaceId, "--cwd", ctx.cwd, "--no-focus"] as const;
+			const createdTab = await herdr.exec(tabCreateArgs, { cwd: ctx.cwd });
+			if (createdTab.code !== 0 || createdTab.killed) {
+				const createError = new Error(herdrCommandFailure(tabCreateArgs, createdTab));
+				try {
+					await unlink(cloneFile);
+				} catch (cleanupError) {
+					throw new AggregateError(
+						[createError, cleanupError],
+						`${createError.message} Clone cleanup also failed for ${cloneFile}: ${errorMessage(cleanupError)}`,
+					);
+				}
+				throw createError;
+			}
+
+			let tabId: string | undefined;
+			let rootPaneId: string | undefined;
+			try {
+				const tabResponse: unknown = JSON.parse(createdTab.stdout);
+				if (!tabResponse || typeof tabResponse !== "object" || Array.isArray(tabResponse)) {
+					throw new Error("Herdr tab create returned invalid JSON");
+				}
+				const result = (tabResponse as {
+					result?: { tab?: { tab_id?: unknown }; root_pane?: { pane_id?: unknown } };
+				}).result;
+				tabId = requiredString(result?.tab?.tab_id, "Herdr tab response tab_id");
+				rootPaneId = requiredString(result?.root_pane?.pane_id, `Herdr tab ${tabId} root pane_id`);
+			} catch (error) {
+				throw new Error(
+					`Clone launch could not be confirmed after creating a Herdr tab; retained${tabId ? ` Herdr tab ${tabId} and` : ""} session ${cloneFile}: ${errorMessage(error)}`,
+					{ cause: error },
+				);
+			}
+			if (!tabId || !rootPaneId) {
+				throw new Error(`Clone launch could not be confirmed after creating a Herdr tab; retained session ${cloneFile}.`);
+			}
+
+			const agentName = `clone-${randomUUID().replaceAll("-", "").slice(0, 24)}`;
+			const startArgs = [
+				"agent", "start", agentName, "--kind", "pi", "--pane", rootPaneId,
+				"--", "--session", cloneFile,
+			];
+			try {
+				for (let attempt = 1; attempt <= 5; attempt += 1) {
+					const result = await herdr.exec(startArgs, { cwd: ctx.cwd });
+					if (result.code === 0 && !result.killed) break;
+					if (!hasHerdrErrorCode(result, "agent_pane_busy") || attempt === 5) {
+						throw new Error(herdrCommandFailure(startArgs, result));
+					}
+					await delay(250);
+				}
+			} catch (error) {
+				throw new Error(
+					`Clone launch could not be confirmed after starting agent ${agentName}; retained Herdr tab ${tabId}, root pane ${rootPaneId}, and session ${cloneFile}: ${errorMessage(error)}`,
+					{ cause: error },
+				);
+			}
+
+			try {
+				await herdr.run(["tab", "focus", tabId], { cwd: ctx.cwd });
+			} catch (error) {
+				ctx.ui.notify(
+					`Clone agent ${agentName} started in Herdr tab ${tabId} (root pane ${rootPaneId}), but focus failed: ${errorMessage(error)}`,
+					"warning",
+				);
+				return;
+			}
+			ctx.ui.notify(
+				`Cloned current conversation into Herdr tab ${tabId} (root pane ${rootPaneId}, agent ${agentName}).`,
+				"info",
+			);
+		},
+	});
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@henryqw/pi-herdr-clone",
+  "version": "0.1.1",
+  "description": "Clone the current Pi conversation path into a new Herdr tab.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "herdr",
+    "session",
+    "clone"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/*.ts test/*.test.ts",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.2"
+  },
+  "dependencies": {
+    "@henryqw/pi-herdr": "^0.1.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HenryQW/pi-packages.git",
+    "directory": "packages/pi-herdr-clone"
+  },
+  "bugs": {
+    "url": "https://github.com/HenryQW/pi-packages/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  }
+}