@hcflabs/pi-herdr-tools 1.6.7 → 1.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -61,9 +61,14 @@ Worktree creation uses `herdr worktree create --workspace <current-workspace> --
61
61
 
62
62
  Run `/handoff-worktree Fix the flaky login test`. The agent collects missing facts, asking one question only for an unclear repository, outcome, or critical constraint. It sends a self-contained prompt, not the conversation, and reports without waiting for completion.
63
63
 
64
- The tool registers only with `HERDR_ENV=1`. It also requires `HERDR_PANE_ID`, local `main`, and matching Git repositories for the current directory and pane workspace.
64
+ The tool registers only with `HERDR_ENV=1`. It also requires `HERDR_PANE_ID` and local `main`. A handoff has no checked integration: the new agent works without supervision. Delegated subagents cannot use the tool.
65
65
 
66
- All parameters must be non-empty strings:
66
+ The tool selects the repository in one of two ways:
67
+
68
+ - Without `repo`, the current directory and the pane workspace must be in the same Git repository.
69
+ - With `repo`, the tool uses that child repository of the Pi working directory. Use it when Pi runs in a parent directory that holds many repositories. The current workspace does not need a Git checkout.
70
+
71
+ The tool never selects a child repository automatically. All parameters must be non-empty strings:
67
72
 
68
73
  | Parameter | Requirement |
69
74
  | --- | --- |
@@ -71,8 +76,9 @@ All parameters must be non-empty strings:
71
76
  | `label` | Workspace label. |
72
77
  | `agentName` | Unique agent name matching `^[a-z][a-z0-9_-]{0,31}$`. |
73
78
  | `prompt` | Self-contained task prompt. |
79
+ | `repo` | Optional. A Git top-level directory, relative to the Pi working directory. It must not contain `..` or resolve outside that directory. A subdirectory of a repository fails. |
74
80
 
75
- After validation, the tool runs `herdr worktree create --workspace <parent> --branch <branch> --base main --label <label> --no-focus`. It starts Pi without session arguments. It submits `herdr agent prompt <agentName> <prompt> --wait --until working --timeout 30000`, with the prompt as one argument, not a shell command or file. The result includes workspace ID, tab, pane, branch, checkout path, and agent name.
81
+ After validation, the tool runs `herdr worktree create --workspace <parent> --branch <branch> --base main --label <label> --no-focus`. With `repo`, it uses `--cwd <repository>` instead of `--workspace <parent>`. Herdr then opens the primary workspace of the repository, or creates it, and does not close it later. It starts Pi without session arguments. It submits `herdr agent prompt <agentName> <prompt> --wait --until working --timeout 30000`, with the prompt as one argument, not a shell command or file. The result includes workspace ID, tab, pane, branch, checkout path, agent name, and `repo` when set.
76
82
 
77
83
  ### Side questions
78
84
 
@@ -108,7 +114,9 @@ Status clears on answer, cancellation, failure, `/reload`, session switch, or ex
108
114
 
109
115
  ![Worktree removal and primary-checkout update.](./docs/done-flow.svg)
110
116
 
111
- `/done` requires `HERDR_ENV=1`, `HERDR_WORKSPACE_ID`, and `HERDR_TAB_ID`. Commit or discard changes, then confirm removal; declining changes nothing. Normal and forced completion wait for idle Pi.
117
+ `/done` requires `HERDR_ENV=1`, `HERDR_PANE_ID`, and `HERDR_TAB_ID`. Commit or discard changes, then confirm removal; declining changes nothing. Normal and forced completion wait for idle Pi.
118
+
119
+ `/done` gets the checkout from the Herdr workspace of the current pane, not from the Pi working directory. Pi can run in a subdirectory of the checkout. `/done` refuses a workspace that is not a linked Git worktree, and it then changes nothing.
112
120
 
113
121
  Normal removal rejects dirty worktrees and checkout use by other workspaces. Close listed tabs and retry; labels identify them, or IDs without labels. Primary-checkout tabs do not block removal or updates.
114
122
 
package/internal/done.ts CHANGED
@@ -1,6 +1,8 @@
1
+ import { realpath } from "node:fs/promises";
1
2
  import { tmpdir } from "node:os";
2
3
  import type { ExecResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
3
4
  import { createHerdrClient, withWorktreeLock } from "@hcflabs/pi-herdr";
5
+ import { resolveWorkspace } from "./worktree.ts";
4
6
 
5
7
  type SnapshotPane = { tab_id?: unknown; cwd?: unknown };
6
8
  type TabEntry = { tab_id?: unknown; workspace_id?: unknown; label?: unknown };
@@ -27,8 +29,8 @@ export default function herdrDoneExtension(pi: ExtensionAPI): void {
27
29
  }
28
30
  const tabId = process.env.HERDR_TAB_ID?.trim();
29
31
  if (!tabId) throw new Error("HERDR_TAB_ID is missing.");
30
- const workspaceId = process.env.HERDR_WORKSPACE_ID?.trim();
31
- if (!workspaceId) throw new Error("HERDR_WORKSPACE_ID is missing.");
32
+ const paneId = process.env.HERDR_PANE_ID?.trim();
33
+ if (!paneId) throw new Error("HERDR_PANE_ID is missing.");
32
34
 
33
35
  if (!force) {
34
36
  const confirmed = await ctx.ui.confirm("Done", "Close its Herdr tabs and remove the current worktree?");
@@ -36,7 +38,15 @@ export default function herdrDoneExtension(pi: ExtensionAPI): void {
36
38
  }
37
39
 
38
40
  await ctx.waitForIdle();
39
- const checkout = (await execOrThrow("git", ["rev-parse", "--show-toplevel"], ctx.cwd)).trim();
41
+ // The checkout comes from the Herdr workspace of this pane, not from the Pi working directory.
42
+ // Pi can run in a parent directory or a subdirectory of the checkout.
43
+ const workspace = await resolveWorkspace(herdr, ctx.cwd, paneId);
44
+ const workspaceId = workspace.workspaceId;
45
+ if (!workspace.isLinkedWorktree || !workspace.checkout) {
46
+ throw new Error(`/done: Herdr workspace ${workspaceId} is not a linked Git worktree. Nothing was removed.`);
47
+ }
48
+ // Herdr can report a path without symlink resolution. Git and pane paths use the real path.
49
+ const checkout = await realpath(workspace.checkout);
40
50
  // First record of the NUL-delimited list is always the main worktree;
41
51
  // -z keeps paths containing newlines parseable.
42
52
  const worktreeFields = (await execOrThrow("git", ["worktree", "list", "--porcelain", "-z"], checkout)).split("\0");
@@ -78,9 +88,10 @@ export default function herdrDoneExtension(pi: ExtensionAPI): void {
78
88
  throw new Error(`Worktree still used by Herdr tabs ${names.join(", ")}; close them first.`);
79
89
  }
80
90
 
91
+ // Run Git in the primary checkout of the same repository. Pi's cwd can be outside it.
81
92
  await execOrThrow("git", [
82
93
  "worktree", "remove", ...(force ? ["--force"] : []), checkout,
83
- ], ctx.cwd);
94
+ ], mainCheckout);
84
95
  return siblingTabIds;
85
96
  });
86
97
  try {
@@ -1,5 +1,6 @@
1
1
  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
2
  import { createHerdrClient, herdrCommandFailure } from "@hcflabs/pi-herdr";
3
+ import { resolveRepoTarget } from "@hcflabs/pi-repo";
3
4
  import { Type } from "typebox";
4
5
  import {
5
6
  createWorktree,
@@ -24,6 +25,9 @@ const HandoffParams = Type.Object({
24
25
  pattern: "^[a-z][a-z0-9_-]{0,31}$",
25
26
  }),
26
27
  prompt: nonEmpty("Self-contained task prompt for the new agent"),
28
+ repo: Type.Optional(nonEmpty(
29
+ "Child Git repository for the worktree, as a path relative to the Pi working directory. Omit it to use the repository of the current Herdr workspace.",
30
+ )),
27
31
  });
28
32
 
29
33
  /** Register `herdr_handoff` only inside Herdr, where it can run. */
@@ -37,39 +41,59 @@ export default function herdrHandoffExtension(pi: ExtensionAPI): void {
37
41
  description: "Create a Herdr worktree from local main, start Pi in it, and submit a self-contained task prompt. Focus does not change.",
38
42
  promptSnippet: "Hand off a separate task to a new Pi agent in a new Herdr worktree from local main",
39
43
  promptGuidelines: [
40
- "Use herdr_handoff only when the user asks to hand off a task to a new worktree, for example through /handoff-worktree.",
44
+ "Use herdr_handoff for a separate task that the user authorized, for example through /handoff-worktree. A handoff has no checked integration: the new agent works unsupervised.",
45
+ "When the Pi working directory holds several repositories, set repo to the child repository of the task. herdr_handoff never selects a repository automatically.",
41
46
  ],
42
47
  parameters: HandoffParams,
43
48
  executionMode: "sequential",
44
49
 
45
- async execute(_toolCallId, { branch, label, agentName, prompt }, signal, _onUpdate, ctx) {
50
+ async execute(_toolCallId, { branch, label, agentName, prompt, repo }, signal, _onUpdate, ctx) {
46
51
  const paneId = requiredString(process.env.HERDR_PANE_ID, "HERDR_PANE_ID");
47
- const workspace = await resolveWorkspace(herdr, ctx.cwd, paneId);
48
- const checkout = requiredString(workspace.checkout, `Git checkout of Herdr workspace ${workspace.workspaceId}`);
49
52
  const git = (cwd: string, args: string[]) => pi.exec("git", args, { cwd });
50
- const repository = async (cwd: string) => {
51
- const result = await git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
52
- if (result.code !== 0 || result.killed) throw new Error(`herdr_handoff: ${cwd} is not in a Git repository; nothing was created.`);
53
- return result.stdout.trim();
54
- };
55
- // The worktree comes from the pane's workspace, so it must be the repository checked here.
56
- if (await repository(ctx.cwd) !== await repository(checkout)) {
57
- throw new Error(`herdr_handoff: ${ctx.cwd} and Herdr workspace ${workspace.workspaceId} (${checkout}) are different Git repositories; nothing was created.`);
53
+ let gitCwd: string;
54
+ let location: string[];
55
+ if (repo === undefined) {
56
+ const workspace = await resolveWorkspace(herdr, ctx.cwd, paneId);
57
+ if (!workspace.checkout) {
58
+ throw new Error(
59
+ `herdr_handoff: Herdr workspace ${workspace.workspaceId} has no Git checkout. Set repo to a child repository relative to ${ctx.cwd}; nothing was created.`,
60
+ );
61
+ }
62
+ const repository = async (cwd: string) => {
63
+ const result = await git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
64
+ if (result.code !== 0 || result.killed) throw new Error(`herdr_handoff: ${cwd} is not in a Git repository; nothing was created.`);
65
+ return result.stdout.trim();
66
+ };
67
+ // The worktree comes from the pane's workspace, so it must be the repository checked here.
68
+ if (await repository(ctx.cwd) !== await repository(workspace.checkout)) {
69
+ throw new Error(`herdr_handoff: ${ctx.cwd} and Herdr workspace ${workspace.workspaceId} (${workspace.checkout}) are different Git repositories; nothing was created.`);
70
+ }
71
+ gitCwd = ctx.cwd;
72
+ location = ["--workspace", await worktreeParentWorkspace(herdr, ctx.cwd, workspace)];
73
+ } else {
74
+ // Herdr opens or creates the repository's primary workspace when it gets --cwd.
75
+ const target = await resolveRepoTarget(ctx.cwd, repo, {
76
+ signal,
77
+ runProcess: (command, args, options) => pi.exec(command, args, { cwd: options.cwd, signal: options.signal, timeout: options.timeoutMs ?? undefined }),
78
+ }).catch((error: unknown) => {
79
+ throw new Error(`herdr_handoff: ${errorMessage(error)} Nothing was created.`, { cause: error });
80
+ });
81
+ gitCwd = target.root;
82
+ location = ["--cwd", target.root];
58
83
  }
59
- const main = await git(ctx.cwd, ["rev-parse", "--verify", "--quiet", "refs/heads/main"]);
84
+ const main = await git(gitCwd, ["rev-parse", "--verify", "--quiet", "refs/heads/main"]);
60
85
  if (main.code !== 0 || main.killed) {
61
- throw new Error(`herdr_handoff requires a local main branch in ${ctx.cwd}; nothing was created.`);
86
+ throw new Error(`herdr_handoff requires a local main branch in ${gitCwd}; nothing was created.`);
62
87
  }
63
88
  // Herdr checks out an existing branch instead of creating it from --base.
64
- const existing = await git(ctx.cwd, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
89
+ const existing = await git(gitCwd, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
65
90
  if (existing.code !== 1 || existing.killed) {
66
91
  throw new Error(`herdr_handoff: branch ${branch} already exists or could not be checked; choose a new branch. Nothing was created.`);
67
92
  }
68
- const parentId = await worktreeParentWorkspace(herdr, ctx.cwd, workspace);
69
93
 
70
94
  signal?.throwIfAborted();
71
95
  const worktree = await createWorktree(herdr, ctx.cwd, [
72
- "worktree", "create", "--workspace", parentId,
96
+ "worktree", "create", ...location,
73
97
  "--branch", branch, "--base", "main", "--label", label, "--no-focus",
74
98
  ], "Handoff");
75
99
  const { workspaceId, checkoutPath } = worktree;
@@ -95,7 +119,7 @@ export default function herdrHandoffExtension(pi: ExtensionAPI): void {
95
119
  );
96
120
  }
97
121
 
98
- const details = { workspaceId, tabId: target.tabId, paneId: target.paneId, branch, checkoutPath, agentName };
122
+ const details = { workspaceId, tabId: target.tabId, paneId: target.paneId, branch, checkoutPath, agentName, ...(repo === undefined ? {} : { repo }) };
99
123
  return {
100
124
  content: [{
101
125
  type: "text" as const,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hcflabs/pi-herdr-tools",
3
- "version": "1.6.7",
3
+ "version": "1.7.1",
4
4
  "description": "Clone, hand off, name, and finish Pi conversations in Herdr, with mergeable side questions.",
5
5
  "keywords": ["pi-package", "pi", "herdr", "session", "clone", "side-thread", "title"],
6
6
  "type": "module",
@@ -21,6 +21,7 @@
21
21
  "dependencies": {
22
22
  "@hcflabs/pi-config-store": "^4.0.0",
23
23
  "@hcflabs/pi-herdr": "^0.5.0",
24
+ "@hcflabs/pi-repo": "^0.1.0",
24
25
  "@hcflabs/pi-task-models": "^9.0.0"
25
26
  },
26
27
  "devDependencies": {
@@ -9,5 +9,5 @@ If the issue is empty, stop and ask the user to run `/handoff-worktree <issue>`.
9
9
 
10
10
  1. Gather only the missing facts from the conversation and the repository. Ask one focused question only if the repository, expected outcome, or a critical constraint is unclear.
11
11
  2. Write one self-contained prompt: problem, evidence, expected outcome, constraints, starting files, validation, and requested delivery. Exclude unrelated context, secrets, and stale runtime IDs.
12
- 3. Choose a concise branch, a short label, and a unique agent name.
12
+ 3. Choose a concise branch, a short label, and a unique agent name. If the Pi working directory holds several repositories, also choose `repo`: the path of the child repository, relative to the working directory.
13
13
  4. Call `herdr_handoff` with them. Report its result. Do not wait for the new agent to finish.