@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 +12 -4
- package/internal/done.ts +15 -4
- package/internal/handoff.ts +42 -18
- package/package.json +2 -1
- package/prompts/handoff-worktree.md +1 -1
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
|
|
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
|
-
|
|
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
|
|
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
|

|
|
110
116
|
|
|
111
|
-
`/done` requires `HERDR_ENV=1`, `
|
|
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
|
|
31
|
-
if (!
|
|
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
|
-
|
|
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
|
-
],
|
|
94
|
+
], mainCheckout);
|
|
84
95
|
return siblingTabIds;
|
|
85
96
|
});
|
|
86
97
|
try {
|
package/internal/handoff.ts
CHANGED
|
@@ -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
|
|
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
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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(
|
|
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 ${
|
|
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(
|
|
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",
|
|
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.
|
|
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.
|