@hcflabs/pi-herdr-tools 1.6.7 → 1.7.0

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
 
@@ -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.0",
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.