@deathbeam/pi-delegate 0.0.30 → 0.0.31
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 +6 -3
- package/format.ts +1 -1
- package/index.ts +116 -58
- package/package.json +1 -1
- package/store.ts +4 -5
package/README.md
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# [@deathbeam/pi-delegate](https://www.npmjs.com/package/@deathbeam/pi-delegate)
|
|
2
2
|
|
|
3
|
-
Run subagents with `delegate`, `delegate_list`, `delegate_steer`, `delegate_cancel`,
|
|
3
|
+
Run subagents with `delegate`, `delegate_list`, `delegate_steer`, `delegate_cancel`, `delegate_apply`, and
|
|
4
|
+
`delegate_discard`.
|
|
4
5
|
Use `/delegate` command to inspect jobs in a full-screen TUI.
|
|
5
6
|
|
|
6
7
|
## Installation
|
|
@@ -51,10 +52,12 @@ Explore the codebase and report relevant paths.
|
|
|
51
52
|
## Isolation
|
|
52
53
|
|
|
53
54
|
`isolated: true` (on a `delegate` call or in agent frontmatter) runs the delegate in its own git clone at
|
|
54
|
-
`.pi/worktrees/<id>`, starting from your current working tree including uncommitted changes.
|
|
55
|
-
`.gitignore`.
|
|
55
|
+
`.pi/worktrees/<id>`, starting from your current working tree including uncommitted changes.
|
|
56
56
|
|
|
57
57
|
`delegate_apply` merges the result into your working tree as uncommitted changes.
|
|
58
|
+
`delegate_discard` discards the clone and its changes.
|
|
59
|
+
|
|
60
|
+
Any later delegate can share that clone with `clone: <job id>`, for review, tests, or follow-up work.
|
|
58
61
|
|
|
59
62
|
## Development
|
|
60
63
|
|
package/format.ts
CHANGED
|
@@ -280,7 +280,7 @@ export function reportText(report: DelegateReport): string {
|
|
|
280
280
|
// The apply hint is for the model only: the transcript renders `output`, so users never see it.
|
|
281
281
|
const hint =
|
|
282
282
|
report.isolation && !report.cloneClosed
|
|
283
|
-
? `\n\nCall delegate_apply with job ${report.id} to land its changes.`
|
|
283
|
+
? `\n\nCall delegate_apply with job ${report.id} to land its changes, or delegate_discard to drop them.`
|
|
284
284
|
: "";
|
|
285
285
|
return `${head} finished.${output ? `\n\n${output}` : ""}${hint}`;
|
|
286
286
|
}
|
package/index.ts
CHANGED
|
@@ -50,7 +50,14 @@ type SteerDetails = Pick<
|
|
|
50
50
|
elapsedMs: number;
|
|
51
51
|
};
|
|
52
52
|
|
|
53
|
-
const DELEGATION_TOOLS = new Set([
|
|
53
|
+
const DELEGATION_TOOLS = new Set([
|
|
54
|
+
"delegate",
|
|
55
|
+
"delegate_apply",
|
|
56
|
+
"delegate_discard",
|
|
57
|
+
"delegate_list",
|
|
58
|
+
"delegate_steer",
|
|
59
|
+
"delegate_cancel",
|
|
60
|
+
]);
|
|
54
61
|
const WIDGET_KEY = "delegate";
|
|
55
62
|
const RESULT_MESSAGE = "delegate-result";
|
|
56
63
|
const REMINDER_MESSAGE = "delegate-reminder";
|
|
@@ -102,6 +109,39 @@ export default function (pi: ExtensionAPI) {
|
|
|
102
109
|
return job ? jobIdentity(theme, job) : theme.fg("muted", id || "…");
|
|
103
110
|
};
|
|
104
111
|
|
|
112
|
+
/** The clone is the unit: every job id that ran in it is only a handle, so state changes reach all of them. */
|
|
113
|
+
const jobsInClone = (clone: string) => store.all().filter((job) => job.isolation?.clone === clone);
|
|
114
|
+
|
|
115
|
+
/** A job that still has a clone; any job id that ran in a clone is a handle on it. */
|
|
116
|
+
const clonedJob = (id: string) => {
|
|
117
|
+
const job = store.findOrThrow(id);
|
|
118
|
+
const isolation = job.isolation;
|
|
119
|
+
if (!isolation)
|
|
120
|
+
throw new Error(
|
|
121
|
+
job.cloneClosed
|
|
122
|
+
? `The clone of delegate job "${id}" was already applied or discarded.`
|
|
123
|
+
: `Delegate job "${id}" did not run in an isolated clone.`,
|
|
124
|
+
);
|
|
125
|
+
return { job, isolation };
|
|
126
|
+
};
|
|
127
|
+
|
|
128
|
+
/** Closing a clone is a clone-wide operation: every job id that ran in it stops pointing at it. */
|
|
129
|
+
const closeClone = (isolation: IsolationState) => {
|
|
130
|
+
removeClone(isolation);
|
|
131
|
+
for (const shared of jobsInClone(isolation.clone)) {
|
|
132
|
+
shared.isolation = undefined;
|
|
133
|
+
shared.cloneClosed = true;
|
|
134
|
+
store.save(shared);
|
|
135
|
+
}
|
|
136
|
+
};
|
|
137
|
+
|
|
138
|
+
/** One job at a time per clone: a shared clone is a shared working directory. */
|
|
139
|
+
const requireIdleClone = (isolation: IsolationState) => {
|
|
140
|
+
const busy = store.live().find((job) => job.isolation?.clone === isolation.clone);
|
|
141
|
+
if (busy)
|
|
142
|
+
throw new Error(`Delegate job "${busy.id}" is running in this clone; wait for it or cancel it first.`);
|
|
143
|
+
};
|
|
144
|
+
|
|
105
145
|
const refreshWidget = (ctx: ExtensionContext) => {
|
|
106
146
|
if (!ctx.hasUI) return;
|
|
107
147
|
store.notify();
|
|
@@ -173,7 +213,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
173
213
|
ctx: ExtensionContext,
|
|
174
214
|
agent: AgentFile,
|
|
175
215
|
prior: InspectJob | undefined,
|
|
176
|
-
fields: { description: string; model?: string; isolated?: boolean },
|
|
216
|
+
fields: { description: string; model?: string; isolated?: boolean; clone?: IsolationState },
|
|
177
217
|
task: string,
|
|
178
218
|
signal: AbortSignal | undefined,
|
|
179
219
|
prompt = task,
|
|
@@ -184,7 +224,9 @@ export default function (pi: ExtensionAPI) {
|
|
|
184
224
|
);
|
|
185
225
|
const displayModel = thinking ? `${model}:${thinking}` : model;
|
|
186
226
|
const id = prior?.id ?? randomUUID().slice(0, 8);
|
|
187
|
-
const isolation =
|
|
227
|
+
const isolation =
|
|
228
|
+
prior?.isolation ?? fields.clone ?? (fields.isolated ? createIsolation(ctx.cwd, id) : undefined);
|
|
229
|
+
if (isolation) requireIdleClone(isolation);
|
|
188
230
|
|
|
189
231
|
const job: DelegateJob = {
|
|
190
232
|
// A revived job keeps its id: the pinned child session id reopens the old transcript.
|
|
@@ -233,14 +275,15 @@ export default function (pi: ExtensionAPI) {
|
|
|
233
275
|
shell: false,
|
|
234
276
|
stdio: "pipe",
|
|
235
277
|
});
|
|
236
|
-
store.launch(job
|
|
278
|
+
store.launch(job);
|
|
237
279
|
const isolatedPrompt = isolation
|
|
238
|
-
? `You are working in an isolated git clone at ${isolation.clone}; the main working tree is untouched. Commit freely here; the orchestrator applies your changes to the main tree.`
|
|
280
|
+
? `You are working in an isolated git clone at ${isolation.clone}; the main working tree is untouched. Commit freely here; the orchestrator applies your changes to the main tree. \`git diff main-snapshot\` shows all changes made in this clone.`
|
|
239
281
|
: "";
|
|
240
282
|
const run = runChild(
|
|
241
283
|
child,
|
|
242
284
|
isolatedPrompt ? `${isolatedPrompt}\n\n${prompt}` : prompt,
|
|
243
|
-
|
|
285
|
+
// Foreground runs also stop on the tool's own abort (Esc); delegate_cancel and shutdown use the controller.
|
|
286
|
+
details.background || !signal ? job.controller.signal : AbortSignal.any([signal, job.controller.signal]),
|
|
244
287
|
(update) => store.record(job, update),
|
|
245
288
|
Boolean(prior),
|
|
246
289
|
);
|
|
@@ -389,7 +432,9 @@ export default function (pi: ExtensionAPI) {
|
|
|
389
432
|
"",
|
|
390
433
|
"A delegate gets the project instructions but not this conversation: it cannot see the user's request, the files you read, or your decisions. Write `task` as a self-contained brief: the goal and why, what you already know (paths, symbols, errors), scope and constraints, whether to edit files or only report, and what to return (format, length, path:line evidence).",
|
|
391
434
|
"",
|
|
392
|
-
"With isolated: true, the delegate runs in an isolated git clone at .pi/worktrees/<job id> (gitignore that path), starting from the main tree exactly as it is now, uncommitted and untracked files included. It never touches the main tree and may commit freely; delegate_apply brings its changes back.",
|
|
435
|
+
"With isolated: true, the delegate runs in an isolated git clone at .pi/worktrees/<job id> (gitignore that path), starting from the main tree exactly as it is now, uncommitted and untracked files included. It never touches the main tree and may commit freely; delegate_apply brings its changes back, delegate_discard drops them.",
|
|
436
|
+
"",
|
|
437
|
+
"To run another delegate in an isolated job's clone, pass that job id as `clone`. Every job id that ran in a clone is a handle on it: delegate_apply or delegate_discard with any of them acts on the whole clone, and only one of them can run at a time.",
|
|
393
438
|
"",
|
|
394
439
|
"To follow up on or redirect an existing job, see delegate_steer.",
|
|
395
440
|
].join("\n"),
|
|
@@ -416,16 +461,24 @@ export default function (pi: ExtensionAPI) {
|
|
|
416
461
|
}),
|
|
417
462
|
),
|
|
418
463
|
isolated: Type.Optional(
|
|
419
|
-
Type.Boolean({ description: "Run in
|
|
464
|
+
Type.Boolean({ description: "Run in a new isolated git clone; apply results with delegate_apply." }),
|
|
465
|
+
),
|
|
466
|
+
clone: Type.Optional(
|
|
467
|
+
Type.String({
|
|
468
|
+
description: "Job id of an isolated delegate; run in its clone instead of the main tree.",
|
|
469
|
+
}),
|
|
420
470
|
),
|
|
421
471
|
}),
|
|
422
472
|
async execute(_toolCallId, rawParams, signal, _onUpdate, ctx) {
|
|
423
473
|
const params = dropNulls(rawParams);
|
|
424
474
|
const { agent: agentName, description, task, model, isolated } = params;
|
|
425
475
|
if (!agentName || !description || !task) throw new Error("agent, description and task are required.");
|
|
476
|
+
const cloneId = jobId(params.clone);
|
|
477
|
+
if (cloneId && isolated === false) throw new Error("clone always runs isolated; omit isolated: false.");
|
|
478
|
+
const clone = cloneId ? clonedJob(cloneId).isolation : undefined;
|
|
426
479
|
const agent = agentByName(ctx.cwd, agentName);
|
|
427
|
-
const effective = isolated ?? agent.isolated;
|
|
428
|
-
return runDelegate(ctx, agent, undefined, { description, model, isolated: effective }, task, signal);
|
|
480
|
+
const effective = clone ? true : (isolated ?? agent.isolated);
|
|
481
|
+
return runDelegate(ctx, agent, undefined, { description, model, isolated: effective, clone }, task, signal);
|
|
429
482
|
},
|
|
430
483
|
|
|
431
484
|
renderCall(args, theme, context) {
|
|
@@ -569,7 +622,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
569
622
|
name: "delegate_cancel",
|
|
570
623
|
label: "Cancel delegate",
|
|
571
624
|
description: "Cancel a running delegate by job id. It sends no report; delegate_steer can continue it later.",
|
|
572
|
-
promptSnippet: "Cancel a running
|
|
625
|
+
promptSnippet: "Cancel a running delegate by job id",
|
|
573
626
|
parameters: Type.Object({
|
|
574
627
|
id: Type.String({ description: "Job id from delegate or delegate_list." }),
|
|
575
628
|
}),
|
|
@@ -606,53 +659,29 @@ export default function (pi: ExtensionAPI) {
|
|
|
606
659
|
name: "delegate_apply",
|
|
607
660
|
label: "Apply delegate",
|
|
608
661
|
description:
|
|
609
|
-
"Apply an isolated delegate's changes to the main working tree by job id. The delegate's commits and uncommitted changes are 3-way merged onto a fresh snapshot of the main tree, so nearby but non-overlapping edits apply cleanly; only a true conflict fails. On conflict the clone is kept and the error explains the recovery.
|
|
610
|
-
promptSnippet: "Apply an isolated delegate's clone to the main tree
|
|
662
|
+
"Apply an isolated delegate's changes to the main working tree by job id. The delegate's commits and uncommitted changes are 3-way merged onto a fresh snapshot of the main tree, so nearby but non-overlapping edits apply cleanly; only a true conflict fails. On conflict the clone is kept and the error explains the recovery. No delegate may be running in its clone.",
|
|
663
|
+
promptSnippet: "Apply an isolated delegate's clone to the main tree by job id",
|
|
611
664
|
parameters: Type.Object({
|
|
612
|
-
id: Type.String({ description: "Job id of
|
|
613
|
-
discard: Type.Optional(
|
|
614
|
-
Type.Boolean({ description: "Remove the delegate's clone without applying its changes." }),
|
|
615
|
-
),
|
|
665
|
+
id: Type.String({ description: "Job id of an isolated delegate; any job id that ran in the clone works." }),
|
|
616
666
|
}),
|
|
617
667
|
async execute(_toolCallId, rawParams, _signal, _onUpdate, _ctx) {
|
|
618
668
|
const params = dropNulls(rawParams);
|
|
619
669
|
const id = jobId(params.id);
|
|
620
|
-
const job =
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
if (!job.isolation)
|
|
624
|
-
throw new Error(`Delegate job "${id}" is not isolated; its changes are already in the main tree.`);
|
|
625
|
-
|
|
626
|
-
const isolation = job.isolation;
|
|
627
|
-
const closeClone = () => {
|
|
628
|
-
removeClone(isolation);
|
|
629
|
-
job.isolation = undefined;
|
|
630
|
-
job.cloneClosed = true;
|
|
631
|
-
store.save(job);
|
|
632
|
-
};
|
|
633
|
-
if (params.discard === true) {
|
|
634
|
-
closeClone();
|
|
635
|
-
return {
|
|
636
|
-
content: [
|
|
637
|
-
{
|
|
638
|
-
type: "text",
|
|
639
|
-
text: `Discarded the isolated clone of delegate "${job.agent}" (job ${job.id}); nothing was applied.`,
|
|
640
|
-
},
|
|
641
|
-
],
|
|
642
|
-
details: { id: job.id, agent: job.agent, discarded: true },
|
|
643
|
-
};
|
|
644
|
-
}
|
|
645
|
-
const result = applyClone(job.isolation);
|
|
670
|
+
const { job, isolation } = clonedJob(id);
|
|
671
|
+
requireIdleClone(isolation);
|
|
672
|
+
const result = applyClone(isolation);
|
|
646
673
|
if (result.kind === "conflict") {
|
|
647
674
|
// Base rule: base tracks the newest snapshot, so the next apply works whether or not the delegate rebased yet.
|
|
648
|
-
|
|
649
|
-
|
|
675
|
+
for (const shared of jobsInClone(isolation.clone)) {
|
|
676
|
+
shared.isolation = { ...isolation, base: result.snapshot };
|
|
677
|
+
store.save(shared);
|
|
678
|
+
}
|
|
650
679
|
throw new Error(
|
|
651
|
-
`Main tree changed under delegate job "${job.id}"; conflicting files: ${result.files.join(", ") || "(unknown)"}. The clone at ${
|
|
680
|
+
`Main tree changed under delegate job "${job.id}"; conflicting files: ${result.files.join(", ") || "(unknown)"}. The clone at ${isolation.clone} was kept. Steer job ${job.id} with: "Main tree changed under you. In your clone run \`git rebase main-snapshot\` (or merge), resolve conflicts, commit." Then call delegate_apply again.`,
|
|
652
681
|
);
|
|
653
682
|
}
|
|
654
683
|
const stat = result.kind === "applied" ? `\n${result.stat}` : "";
|
|
655
|
-
closeClone();
|
|
684
|
+
closeClone(isolation);
|
|
656
685
|
return {
|
|
657
686
|
content: [
|
|
658
687
|
{
|
|
@@ -668,22 +697,14 @@ export default function (pi: ExtensionAPI) {
|
|
|
668
697
|
},
|
|
669
698
|
|
|
670
699
|
renderCall(args, theme, context) {
|
|
671
|
-
return toolLayout(
|
|
672
|
-
"delegate_apply",
|
|
673
|
-
jobTarget(args?.id, theme),
|
|
674
|
-
argText(args?.discard) === "true" ? "discard" : "",
|
|
675
|
-
theme,
|
|
676
|
-
context.expanded,
|
|
677
|
-
);
|
|
700
|
+
return toolLayout("delegate_apply", jobTarget(args?.id, theme), "", theme, context.expanded);
|
|
678
701
|
},
|
|
679
702
|
|
|
680
703
|
renderResult(result, { expanded }, theme, context) {
|
|
681
|
-
const details = result.details as
|
|
682
|
-
{ id: string; agent: string; discarded?: boolean; diff?: string } | undefined;
|
|
704
|
+
const details = result.details as { id: string; agent: string; diff?: string } | undefined;
|
|
683
705
|
const body = resultText(result);
|
|
684
706
|
if (context.isError || !details?.agent) return resultFallback(body, theme, context.isError);
|
|
685
|
-
const
|
|
686
|
-
const header = `\n${resultHeader(theme, details, status)}`;
|
|
707
|
+
const header = `\n${resultHeader(theme, details, "changes applied")}`;
|
|
687
708
|
const diff = details.diff?.trim() ? renderDiff(piDiff(details.diff)) : "";
|
|
688
709
|
if (!diff) return new Text(header, 0, 0);
|
|
689
710
|
// Collapsed shows the head like the other delegate previews; expanded shows the full colored diff.
|
|
@@ -697,6 +718,43 @@ export default function (pi: ExtensionAPI) {
|
|
|
697
718
|
},
|
|
698
719
|
});
|
|
699
720
|
|
|
721
|
+
pi.registerTool({
|
|
722
|
+
name: "delegate_discard",
|
|
723
|
+
label: "Discard delegate clone",
|
|
724
|
+
description: "Remove an isolated delegate's clone without applying its changes.",
|
|
725
|
+
promptSnippet: "Discard an isolated delegate's clone by job id",
|
|
726
|
+
parameters: Type.Object({
|
|
727
|
+
id: Type.String({ description: "Job id of an isolated delegate; any job id that ran in the clone works." }),
|
|
728
|
+
}),
|
|
729
|
+
async execute(_toolCallId, rawParams, _signal, _onUpdate, _ctx) {
|
|
730
|
+
const params = dropNulls(rawParams);
|
|
731
|
+
const id = jobId(params.id);
|
|
732
|
+
const { job, isolation } = clonedJob(id);
|
|
733
|
+
requireIdleClone(isolation);
|
|
734
|
+
closeClone(isolation);
|
|
735
|
+
return {
|
|
736
|
+
content: [
|
|
737
|
+
{
|
|
738
|
+
type: "text",
|
|
739
|
+
text: `Discarded the isolated clone of delegate "${job.agent}" (job ${job.id}); nothing was applied.`,
|
|
740
|
+
},
|
|
741
|
+
],
|
|
742
|
+
details: { id: job.id, agent: job.agent, discarded: true },
|
|
743
|
+
};
|
|
744
|
+
},
|
|
745
|
+
|
|
746
|
+
renderCall(args, theme, context) {
|
|
747
|
+
return toolLayout("delegate_discard", jobTarget(args?.id, theme), "", theme, context.expanded);
|
|
748
|
+
},
|
|
749
|
+
|
|
750
|
+
renderResult(result, _options, theme, context) {
|
|
751
|
+
const details = result.details as { id: string; agent: string; discarded?: boolean } | undefined;
|
|
752
|
+
const body = resultText(result);
|
|
753
|
+
if (context.isError || !details?.agent) return resultFallback(body, theme, context.isError);
|
|
754
|
+
return new Text(`\n${resultHeader(theme, details, "clone discarded")}`, 0, 0);
|
|
755
|
+
},
|
|
756
|
+
});
|
|
757
|
+
|
|
700
758
|
pi.registerTool({
|
|
701
759
|
name: "delegate_list",
|
|
702
760
|
label: "List delegates",
|
package/package.json
CHANGED
package/store.ts
CHANGED
|
@@ -95,11 +95,11 @@ export function createJobStore(append: (customType: string, data: InspectJob) =>
|
|
|
95
95
|
return job;
|
|
96
96
|
},
|
|
97
97
|
liveJob: (id: string) => running.get(id),
|
|
98
|
-
/** Writes the launch entry a restarted parent restores from;
|
|
99
|
-
launch: (job: DelegateJob
|
|
98
|
+
/** Writes the launch entry a restarted parent restores from; the job joins the live set until it finishes. */
|
|
99
|
+
launch: (job: DelegateJob) => {
|
|
100
100
|
append(JOB_ENTRY, snapshot(job));
|
|
101
101
|
drop(job.id);
|
|
102
|
-
|
|
102
|
+
running.set(job.id, job);
|
|
103
103
|
},
|
|
104
104
|
record: (job: DelegateJob, update: ChildUpdate) => {
|
|
105
105
|
if (job.status !== "running") return;
|
|
@@ -108,8 +108,7 @@ export function createJobStore(append: (customType: string, data: InspectJob) =>
|
|
|
108
108
|
if (update.lastDetail !== undefined) job.lastDetail = update.lastDetail;
|
|
109
109
|
if (update.lastResult !== undefined) job.lastResult = update.lastResult;
|
|
110
110
|
if (update.contextTokens !== undefined) job.contextTokens = update.contextTokens;
|
|
111
|
-
|
|
112
|
-
if (update.activity && running.has(job.id)) addActivity(job, update.activity);
|
|
111
|
+
if (update.activity) addActivity(job, update.activity);
|
|
113
112
|
},
|
|
114
113
|
/** Leaves the live set and writes the completion entry; false when the job was cancelled. */
|
|
115
114
|
finish: (job: DelegateJob, status: JobStatus, detail?: string): boolean => {
|