@deathbeam/pi-delegate 0.0.14 → 0.0.16

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
@@ -48,6 +48,10 @@ Explore the codebase and report relevant paths.
48
48
  Omit `tools` to inherit active tools. `model` can also be an explicit `provider/model`. The model sees the agent list from
49
49
  when the extension loaded, so run `/reload` after adding agents or changing their descriptions.
50
50
 
51
+ The main session is prompted to act as an orchestrator. When it makes 5, 10, 20, … direct exploration calls (`read`,
52
+ `grep`, `find`, `ls`, shell, web tools) without delegating, a hidden reminder nudges it to delegate the rest. The count
53
+ resets on each prompt and each `delegate` call.
54
+
51
55
  ## Development
52
56
 
53
57
  From this package directory:
package/agents/explore.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: explore
3
- description: "Read-only codebase search: finds files, callers, and data flow. Use proactively for open-ended searches and before editing unfamiliar code; launch one per independent area."
3
+ description: "Read-only codebase search: finds files, callers, and data flow. Use it for anything beyond one targeted search and before editing unfamiliar code; launch several in parallel for separate areas."
4
4
  tools: read, grep, find, ls
5
5
  model: cheap
6
6
  thinking: low
package/agents/general.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: general
3
- description: Multi-step work in its own context; can inspect, edit, run commands, and validate. Use for independent subtasks, repetitive edits across many files, or test and build runs whose output you need only summarized.
3
+ description: Multi-step work in its own context; can inspect, edit, run commands, and validate. Use it for implementation, debugging loops (reproduce, fix, verify), repetitive edits across many files, and test or build runs whose output you need only summarized.
4
4
  tools: read, grep, find, ls, bash, edit, write
5
5
  model: balanced
6
6
  thinking: high
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: researcher
3
- description: Web research with cited sources. Use proactively whenever the answer needs external docs, versions, or current facts, instead of searching and fetching pages yourself.
3
+ description: Web research with cited sources. Use it whenever the answer needs external docs, versions, or current facts, instead of searching and fetching pages yourself.
4
4
  tools: read, web_search, web_fetch
5
5
  model: balanced
6
6
  thinking: medium
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: reviewer
3
- description: Independent review of a diff, plan, or finished change. Use proactively before claiming non-trivial work is done.
3
+ description: Independent review of a diff, plan, or finished change. Use it before claiming non-trivial work is done.
4
4
  tools: read, grep, find, ls, bash
5
5
  model: strong
6
6
  thinking: high
package/index.ts CHANGED
@@ -99,6 +99,10 @@ const DELEGATION_TOOLS = new Set(["delegate", "delegate_list", "delegate_steer",
99
99
  const MODEL_TIERS = new Set(["cheap", "balanced", "strong"]);
100
100
  const WIDGET_KEY = "delegate";
101
101
  const RESULT_MESSAGE = "delegate-result";
102
+ const REMINDER_MESSAGE = "delegate-reminder";
103
+ const JOB_ENTRY = "delegate-job";
104
+ const EXPLORATION_TOOLS = new Set(["read", "grep", "find", "ls", "bash", "powershell", "web_search", "web_fetch"]);
105
+ const FIRST_REMINDER_AT = 5;
102
106
  const TASK_PREVIEW_LINES = 5;
103
107
 
104
108
  function expandPath(value: string, cwd: string): string {
@@ -245,6 +249,9 @@ export default function (pi: ExtensionAPI) {
245
249
  const recent: InspectJob[] = [];
246
250
  let viewing: (() => void) | undefined;
247
251
  let ticker: ReturnType<typeof setInterval> | undefined;
252
+ // Prompts are read once; drift happens one quick search at a time, so count it and nudge at 5, 10, 20, ...
253
+ let directCalls = 0;
254
+ let nextReminder = FIRST_REMINDER_AT;
248
255
 
249
256
  const addActivity = (job: DelegateJob, activity: ChildActivity) => {
250
257
  const normalize = (text: string) => text.replace(/\s+/g, " ").trim();
@@ -264,7 +271,9 @@ export default function (pi: ExtensionAPI) {
264
271
  job.status = status;
265
272
  if (detail) addActivity(job, { kind: "status", text: detail });
266
273
  const { controller, steer, lastTool, lastDetail, lastResult, ...snapshot } = job;
267
- recent.unshift({ ...snapshot, endedAt: Date.now() });
274
+ const entry: InspectJob = { ...snapshot, endedAt: Date.now() };
275
+ recent.unshift(entry);
276
+ pi.appendEntry(JOB_ENTRY, entry);
268
277
  };
269
278
 
270
279
  const jobSnapshot = (job: DelegateJob) => ({
@@ -350,6 +359,44 @@ export default function (pi: ExtensionAPI) {
350
359
  viewing = undefined;
351
360
  });
352
361
 
362
+ // Rebuilt from the active branch, like pi's todo example; abandoned branches are alternative histories.
363
+ const restoreJobs = (ctx: ExtensionContext) => {
364
+ recent.length = 0;
365
+ for (const entry of ctx.sessionManager.getBranch()) {
366
+ if (entry.type !== "custom" || entry.customType !== JOB_ENTRY || !entry.data) continue;
367
+ recent.unshift(entry.data as InspectJob);
368
+ }
369
+ };
370
+ pi.on("session_start", (_event, ctx) => restoreJobs(ctx));
371
+ pi.on("session_tree", (_event, ctx) => restoreJobs(ctx));
372
+
373
+ pi.on("before_agent_start", () => {
374
+ directCalls = 0;
375
+ nextReminder = FIRST_REMINDER_AT;
376
+ });
377
+
378
+ pi.on("tool_result", (event) => {
379
+ // Children run without the delegation tools, so only the orchestrating session is nudged.
380
+ if (!pi.getActiveTools().includes("delegate")) return;
381
+ if (event.toolName === "delegate") {
382
+ directCalls = 0;
383
+ nextReminder = FIRST_REMINDER_AT;
384
+ return;
385
+ }
386
+ // Calls a script or another tool issued are not the model's own steps.
387
+ if (event.parentToolCallId || !EXPLORATION_TOOLS.has(event.toolName) || ++directCalls < nextReminder) return;
388
+ nextReminder *= 2;
389
+ // Steering lands after the current tool batch, so it never cuts parallel calls short.
390
+ pi.sendMessage(
391
+ {
392
+ customType: REMINDER_MESSAGE,
393
+ content: `<system-reminder>You have made ${directCalls} direct exploration calls since your last delegation. If what remains is exploration, research, or a build/test/debug loop, delegate it now, in parallel for independent scopes, instead of continuing yourself.</system-reminder>`,
394
+ display: false,
395
+ },
396
+ { deliverAs: "steer" },
397
+ );
398
+ });
399
+
353
400
  pi.registerMessageRenderer(RESULT_MESSAGE, (message, { expanded }, theme) => {
354
401
  const report = message.details as DelegateReport | undefined;
355
402
  if (!report?.agent) return undefined;
@@ -617,20 +664,21 @@ export default function (pi: ExtensionAPI) {
617
664
  name: "delegate",
618
665
  label: "Delegate",
619
666
  description: [
620
- "Start a background Pi agent on one focused task. Returns a job id immediately; the agent's report arrives later as a follow-up message.",
667
+ "Start a delegate: a background run of one of the agents below on one focused task. Returns a job id immediately; the report arrives later as a follow-up message.",
621
668
  "",
622
669
  "Available agents (default model in parentheses):",
623
670
  ...agentList,
624
671
  "",
625
- "The agent 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).",
672
+ "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).",
626
673
  ].join("\n"),
627
674
  promptSnippet:
628
675
  "Delegate a focused task to a background agent with its own context; only its report comes back, as a later follow-up message",
629
676
  promptGuidelines: [
630
- "Delegation is authorized: use delegate proactively, without waiting for the user to ask, whenever work matches an agent's description. Your context is the scarce resource: everything you read stays in it, is re-sent with every later request, and brings compaction closer. A delegate works in a fresh context, often on a cheaper model, and returns only its report.",
631
- "Delegate when you need the conclusion rather than the raw material: open-ended searches (more than ~3 queries), understanding code across several files you will not edit, web research, long command output such as test runs and builds, independent subtasks, and reviews of finished work. Work directly for a known file path, one targeted search, a quick command, or code you will edit yourself. Once direct searching passes ~3 queries, delegate the rest.",
632
- "Start every independent delegate before waiting on any, ideally in one message. Keep decisions and synthesis yourself. Trust reports instead of repeating their searches; read only what you act on.",
633
- "While delegates run, stay outside their scopes; delegate any new context-heavy investigation before tracing it yourself. When a report is the next dependency, end your turn with a brief waiting status. Completion will wake you.",
677
+ "You are the orchestrator, and delegating is your default: plan, split the work, brief delegates, and integrate their reports. Delegation is authorized; do not wait for the user to ask. Your context is the scarce resource: everything you read stays in it, is re-sent with every later request, and brings compaction closer. A delegate works in a fresh context, often on a cheaper model, and returns only its report.",
678
+ "Delegate exploration, research, implementation beyond a small edit, build/test/debug loops, and reviews. Work directly only for reading one known file or the lines you are about to edit, one targeted search, a small edit (about 30 lines in one file), a quick verification (one test run or one cited line), or a command the user asked you to run. Shell one-liners and scripts that search or read code count as exploration, not quick commands.",
679
+ "Your failure mode is drifting into doing the work yourself, one quick search at a time. Decide what to delegate before your first exploratory call; if one targeted search does not settle it, delegate the rest.",
680
+ "Start every independent delegate before waiting on any, ideally in one message. Trust reports instead of repeating their searches; check only what you act on. If a report falls short, delegate a follow-up that names the gap instead of redoing the work yourself.",
681
+ "While delegates run, stay outside their scopes. When a report is the next dependency, end your turn with a brief waiting status. Completion will wake you.",
634
682
  "Read every required delegate report before claiming the task is done. Never sleep, poll, or call any tool solely to wait (including `bash` with `true`, `echo`, or `sleep 0`). Use delegate_list only for a one-time status check.",
635
683
  ],
636
684
  parameters: Type.Object({
@@ -638,7 +686,7 @@ export default function (pi: ExtensionAPI) {
638
686
  description: Type.String({
639
687
  description: "Short 3-8 word summary of this delegation, shown in the transcript.",
640
688
  }),
641
- task: Type.String({ description: "Self-contained brief; the agent cannot see this conversation." }),
689
+ task: Type.String({ description: "Self-contained brief; the delegate cannot see this conversation." }),
642
690
  model: Type.Optional(
643
691
  Type.String({ description: "Model tier (cheap, balanced, strong) or an explicit provider/model." }),
644
692
  ),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deathbeam/pi-delegate",
3
- "version": "0.0.14",
3
+ "version": "0.0.16",
4
4
  "description": "Run focused Pi subagents as background tasks",
5
5
  "type": "module",
6
6
  "license": "MIT",