@deathbeam/pi-delegate 0.0.13 → 0.0.15

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,9 @@ 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 EXPLORATION_TOOLS = new Set(["read", "grep", "find", "ls", "bash", "powershell", "web_search", "web_fetch"]);
104
+ const FIRST_REMINDER_AT = 5;
102
105
  const TASK_PREVIEW_LINES = 5;
103
106
 
104
107
  function expandPath(value: string, cwd: string): string {
@@ -245,6 +248,9 @@ export default function (pi: ExtensionAPI) {
245
248
  const recent: InspectJob[] = [];
246
249
  let viewing: (() => void) | undefined;
247
250
  let ticker: ReturnType<typeof setInterval> | undefined;
251
+ // Prompts are read once; drift happens one quick search at a time, so count it and nudge at 5, 10, 20, ...
252
+ let directCalls = 0;
253
+ let nextReminder = FIRST_REMINDER_AT;
248
254
 
249
255
  const addActivity = (job: DelegateJob, activity: ChildActivity) => {
250
256
  const normalize = (text: string) => text.replace(/\s+/g, " ").trim();
@@ -350,6 +356,33 @@ export default function (pi: ExtensionAPI) {
350
356
  viewing = undefined;
351
357
  });
352
358
 
359
+ pi.on("before_agent_start", () => {
360
+ directCalls = 0;
361
+ nextReminder = FIRST_REMINDER_AT;
362
+ });
363
+
364
+ pi.on("tool_result", (event) => {
365
+ // Children run without the delegation tools, so only the orchestrating session is nudged.
366
+ if (!pi.getActiveTools().includes("delegate")) return;
367
+ if (event.toolName === "delegate") {
368
+ directCalls = 0;
369
+ nextReminder = FIRST_REMINDER_AT;
370
+ return;
371
+ }
372
+ // Calls a script or another tool issued are not the model's own steps.
373
+ if (event.parentToolCallId || !EXPLORATION_TOOLS.has(event.toolName) || ++directCalls < nextReminder) return;
374
+ nextReminder *= 2;
375
+ // Steering lands after the current tool batch, so it never cuts parallel calls short.
376
+ pi.sendMessage(
377
+ {
378
+ customType: REMINDER_MESSAGE,
379
+ 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>`,
380
+ display: false,
381
+ },
382
+ { deliverAs: "steer" },
383
+ );
384
+ });
385
+
353
386
  pi.registerMessageRenderer(RESULT_MESSAGE, (message, { expanded }, theme) => {
354
387
  const report = message.details as DelegateReport | undefined;
355
388
  if (!report?.agent) return undefined;
@@ -617,20 +650,21 @@ export default function (pi: ExtensionAPI) {
617
650
  name: "delegate",
618
651
  label: "Delegate",
619
652
  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.",
653
+ "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
654
  "",
622
655
  "Available agents (default model in parentheses):",
623
656
  ...agentList,
624
657
  "",
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).",
658
+ "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
659
  ].join("\n"),
627
660
  promptSnippet:
628
661
  "Delegate a focused task to a background agent with its own context; only its report comes back, as a later follow-up message",
629
662
  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.",
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.",
663
+ "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.",
664
+ "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.",
665
+ "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.",
666
+ "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.",
667
+ "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
668
  "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
669
  ],
636
670
  parameters: Type.Object({
@@ -638,7 +672,7 @@ export default function (pi: ExtensionAPI) {
638
672
  description: Type.String({
639
673
  description: "Short 3-8 word summary of this delegation, shown in the transcript.",
640
674
  }),
641
- task: Type.String({ description: "Self-contained brief; the agent cannot see this conversation." }),
675
+ task: Type.String({ description: "Self-contained brief; the delegate cannot see this conversation." }),
642
676
  model: Type.Optional(
643
677
  Type.String({ description: "Model tier (cheap, balanced, strong) or an explicit provider/model." }),
644
678
  ),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deathbeam/pi-delegate",
3
- "version": "0.0.13",
3
+ "version": "0.0.15",
4
4
  "description": "Run focused Pi subagents as background tasks",
5
5
  "type": "module",
6
6
  "license": "MIT",