brl-subagent 2.3.4 → 2.3.5

package/AGENT.md

@@ -0,0 +1,88 @@
+# AGENT.md — brl-subagent capability reference (v2.3.4+)
+
+> The `delegate_task` prompt guidelines are a derived summary of this file; if they disagree, this file wins.
+
+This file is the authoritative reference for how the brl-subagent extension behaves
+and how you (the conductor) should judge a delegation. Read it when planning
+delegation-heavy work.
+
+## Execution models
+
+| Mode | What blocks | What wakes you | Batchable? |
+| --- | --- | --- | --- |
+| single, foreground | blocks until it returns | — (result comes back inline) | no |
+| single, background | returns immediately with an agent id | yes — a `subagent-completion` message on terminal state | no |
+| chain | blocks until the chain finishes or fails | — | yes (foreground) |
+| parallel (`tasks`) | blocks until every task finishes | — | yes (foreground) |
+| graph | blocks; runs in waves via `dependsOn` | — | yes (foreground) |
+
+- Foreground single blocks: you wait for the result inline.
+- Background single returns immediately with an agent id; a completion message wakes you (see below).
+- Chain, parallel, and graph are batch — one call, many subtasks. They are foreground today; background batch is future work.
+- Chain stops at the first failure; max 10 steps.
+- Parallel runs every task regardless of the others — no short-circuit.
+- Graph runs in waves, ordered by `dependsOn` edges.
+
+## The completion contract
+
+- A background run wakes you with a structured `subagent-completion` message when it reaches a terminal state (`completed`, `failed`, or `stopped`). The `details` carry `id`, `status`, `errorCategory` (with `errorMessage` when present), cost/tokens/duration, and `label`; the content carries a tail of output.
+- The wake triggers a turn even when you are idle. Do not poll for it.
+- Delivery mode by status holds at knob `"all"`: `failed`/`stopped` → steering you to act; `completed` → follow-up. The `completionNotify` knob changes both the delivery mode and the wake: under `"failed"` a `completed` run is delivered as a passive `nextTurn` (no wake) while `failed`/`stopped` still steer; under `"off"` everything is a passive `nextTurn` and nothing wakes you. (The knob controls whether an idle conductor is triggered — see below.)
+- Knob dependency: polling is correct only when wakes are disabled (`completionNotify: "off"`). The wake is per-terminal-status and knob-scoped: under `"all"` a terminal run always wakes you; under `"failed"` only a `failed` or `stopped` run wakes you — a `completed` run stays a passive `nextTurn` (no wake); under `"off"` nothing wakes you. So polling is wrong unless wakes are disabled. One status check as a stall check is legitimate; repeated polling is not.
+- One message per run — the extension deduplicates on the first terminal event for a run id, so don't expect multiple messages for a single run.
+- Honest records: trust the message's `category`/abort source over your own guess. The provider/abort origin is authoritative on why the run stopped.
+- Steering is not an abort. Being steered to act on a terminal run is not terminating it. A real `stop` is an abort — and a stopped run still wakes you.
+
+## Delegation judgment
+
+- Foreground vs background: if your next step needs the result inline, run foreground. If the user can keep working or is AFK, run background and act on the wake.
+- Batch vs sequential: if the work is pre-declared, use chain/parallel/graph. If you're steering incrementally with the user, issue sequential calls.
+- Retry taxonomy: `retryRunId` is a retry — it re-runs with the recorded task and params. A re-dispatch (a fresh call with the same task text) is not a retry. Never re-issue an identical spec after a termination without confirming the cause with the user (Rule 18).
+- When to delegate: when the task needs an isolated context, a deep investigation, parallel research, or a long-running analysis.
+- Approval: `approvalMode: "always"` is rejected in background — there is no dialog. Use `auto` (default) or `writes`; `writes` auto-approves in background.
+
+## Canonical shapes
+
+- Batch chain with `{previous}`: `chain: [{ task: "…" }, { task: "Use {previous} …" }]` — each step gets the prior step's output.
+- Graph with `dependsOn`: subtasks declare edges; the scheduler runs them in waves.
+- Background + act on wake: spawn a background run, then act when the completion message arrives. Never poll between spawn and wake.
+- retryRunId: pass a failed run's id to re-run it with its recorded task and params; explicit parameters override the originals.
+
+## Mechanics pointer
+
+Presets and templates are documented in the schema, not here. Judgment only:
+
+- Prefer a preset when the delegation matches a standard shape — review/audit/test/docs; override per-call deliberately.
+- Recurring task shapes → a saved template.
+
+The schema's `delegate_task` parameters, the `templateSummary` and `presetRestrictionSummary` lines in the prompt guidelines, and `get_subagent_result`'s description are the mechanics reference.
+
+## Local development
+
+This repo is the package source. Daily use runs the **published npm package**;
+development runs the **local checkout**. Both are `pi install` entries and cannot
+coexist — two loaded copies register the same tools — so remove one first.
+
+```bash
+# Daily: the published artifact — the same thing users install
+pi remove <local-repo-path>
+pi install npm:brl-subagent
+
+# Develop: load the checkout in place — no copying, no syncing
+pi remove npm:brl-subagent
+pi install <local-repo-path>        # or a worktree: …/brl-subagent-wt-<n>
+# then /reload pi after edits
+
+# Back to the published artifact
+pi remove <local-repo-path>
+pi install npm:brl-subagent
+```
+
+A local-path install loads the directory in place and can point at an **unmerged
+worktree**, so it doubles as live verification for a PR. `pi update --extensions`
+advances the npm install and leaves a local-path install alone.
+
+(The former `sync-extension.sh` — rsync into `~/.pi/agent/extensions/brl-subagent`
+— was retired once the package was published: the local-path install supersedes it
+and does not fight `pi update --extensions` by mutating a package-manager-owned
+directory.)

package/README.md

@@ -14,7 +14,7 @@
 - **True background execution** — live monitor, real abort (`stop_subagent`), per-agent timeouts, and hard caps. Nothing orphans; nothing leaks.
 - **Preset-driven tool scoping** — every subagent runs with exactly the tools its job needs, restricted by preset or per-call `tools`/`excludeTools`, with auto-route that picks the right preset when you don't.
 - **Templates with slots** — saved, file-backed task templates with `${param}` placeholders for workflows you run again and again.
-- **Safety by default** — task-fence injection protection, sanitized error paths, owner-only persistence, and a 700+ test suite pinning every contract against the real pi SDK.
+- **Safety by default** — task-fence injection protection, sanitized error paths, owner-only persistence, and a 975+ test suite pinning every contract against the real pi SDK.
 
 ---
 
@@ -22,13 +22,28 @@
 
 ```bash
 # Global (all projects)
-cd ~/.pi/agent/extensions && git clone https://github.com/azmeenafandi/brl-subagent.git
+pi install npm:brl-subagent
 
-# Project-local
-cd your-project/.pi/extensions && git clone https://github.com/azmeenafandi/brl-subagent.git
+# Project-local (commit .pi/settings.json to share with your team)
+pi install -l npm:brl-subagent
 ```
 
-Pi auto-discovers extensions in these directories. To update: `git pull` inside the cloned directory.
+Pi installs the package and loads the extension automatically. Updates and removal:
+
+```bash
+pi update --extensions        # update installed packages
+pi remove npm:brl-subagent    # uninstall
+```
+
+<details>
+<summary>Alternative: install from git</summary>
+
+```bash
+pi install git:github.com/azmeenafandi/brl-subagent@v2.3.4
+```
+
+Git installs are **pinned** to the ref you specify. `pi update --extensions` reconciles to that ref but never advances it — upgrading means re-running `pi install` with a newer `@ref`.
+</details>
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brl-subagent",
-  "version": "2.3.4",
+  "version": "2.3.5",
   "description": "Subagent extension for pi with configurable model and thinking mode via selection UI",
   "keywords": [
     "pi-package"
@@ -16,6 +16,7 @@
     "templates/",
     "README.md",
     "LICENSE",
+    "AGENT.md",
     "!src/__tests__/"
   ],
   "pi": {

package/src/index.ts

@@ -52,6 +52,7 @@ import {
 } from "./types";
 import { validateGraph, topologicalSort } from "./scheduler";
 import { resolveTemplate, loadAllTemplates, loadBuiltinTemplates, validateTemplatePresetRefs, extractParamNames } from "./templates";
+import { pkgPath } from "./paths";
 
 import { sanitizeTask, validateCwd, validateOutputFile, stripAnsi, capOutput, getCurrentDepth, sanitizeErrorMessage, buildCrashResult } from "./sanitize";
 import {
@@ -200,7 +201,7 @@ export default function (pi: ExtensionAPI) {
 	// Read current version from package.json
 	const currentVersion = (() => {
 		try {
-			const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf-8"));
+			const pkg = JSON.parse(fs.readFileSync(pkgPath("package.json"), "utf-8"));
 			return pkg.version || "0.0.0";
 		} catch {
 			return "0.0.0";
@@ -1954,7 +1955,7 @@ export default function (pi: ExtensionAPI) {
 
 	// B1: Load built-in presets once at registration to expose their tool
 	// restrictions to the conductor before any delegate_task call happens.
-	const registrationPresets = loadBuiltinPresets(path.join(__dirname, "..", "presets"));
+	const registrationPresets = loadBuiltinPresets(pkgPath("presets"));
 	const presetRestrictionSummary = buildInventorySummary(registrationPresets, (p) => {
 		const restricted = p.excludeTools?.length || p.tools?.length;
 		if (!restricted) return p.name;
@@ -1965,9 +1966,14 @@ export default function (pi: ExtensionAPI) {
 	// inventory (name + purpose + ${param} slots) to the conductor before any
 	// delegate_task call. Custom/user templates can't be enumerated statically,
 	// so the summary covers built-ins only and points at /brl-subagent templates.
-	const registrationTemplates = loadBuiltinTemplates(path.join(__dirname, "..", "templates"));
+	const registrationTemplates = loadBuiltinTemplates(pkgPath("templates"));
 	const templateSummary = buildInventorySummary(registrationTemplates, formatTemplateSummaryItem);
 
+	// Issue #158: resolve the shipped AGENT.md from the extension's own directory
+	// rather than a hardcoded sync-copy destination, so npm-installed packages
+	// (installed via `pi install npm:brl-subagent`) can find it.
+	const agentMdPath = pkgPath("AGENT.md");
+
 	pi.registerTool({
 		name: "delegate_task",
 		label: "Delegate Task",
@@ -1983,7 +1989,7 @@ export default function (pi: ExtensionAPI) {
 			"Delegate tasks to a subagent for isolated, parallel or background work",
 		promptGuidelines: [
 			"Use delegate_task when the user asks you to hand off work to a subagent, or when a task would benefit from an isolated context window (e.g., deep investigation, parallel research, long-running analysis).",
-			"The authoritative capability reference for delegation is the extension's AGENT.md — read it at ~/.pi/agent/extensions/brl-subagent/AGENT.md, or ./AGENT.md in the project root when present, when planning delegation-heavy work.",
+			`The authoritative capability reference for delegation is the extension's AGENT.md — read it at ${agentMdPath}, or ./AGENT.md in the project root when present, when planning delegation-heavy work.`,
 			"The subagent inherits your system prompt and runs with its own model (configurable via /brl-subagent). It reports what it did when done.",
 			"You can customize per-call via inheritSystemPrompt and systemPrompt: set inheritSystemPrompt: false to save context, provide a systemPrompt for custom instructions, or use both to add instructions on top of inheritance.",
 			"Set thinkingLevel per call to match task complexity. The level is capped at the user's configured maximum. Map tasks to levels using this heuristic: off = file listing, grep, simple read. minimal = file diff, syntax check, find-and-replace. low = refactoring, test generation, documentation. medium = default — code review, debugging, moderate analysis. high = security audit, architecture review, complex debugging. xhigh = multi-step causal reasoning, research, novel problem solving. Default to 'off' or 'minimal' for trivial tasks — do not waste the user's budget.",
@@ -3691,11 +3697,11 @@ export default function (pi: ExtensionAPI) {
 		// Issue #147: capture the session context for the completion-push subscriber.
 		sessionCtx = ctx;
 		// Load built-in presets
-		const presetsDir = path.join(__dirname, "..", "presets");
+		const presetsDir = pkgPath("presets");
 		state.builtinPresets = loadBuiltinPresets(presetsDir, log);
 		state.customPresets = loadCustomPresets(ctx.cwd, log);
 		// Builtin templates + merged full stack (custom overrides builtin)
-		const templatesDir = path.join(__dirname, "..", "templates");
+		const templatesDir = pkgPath("templates");
 		state.builtinTemplates = loadBuiltinTemplates(templatesDir, log);
 		state.config.templates = loadAllTemplates(ctx.cwd, log, templatesDir);
 

package/src/paths.ts

@@ -0,0 +1,25 @@
+/**
+ * brl-subagent — Package-root path resolution
+ *
+ * The extension is loaded from `<pkg>/src/` (package.json `pi.extensions`
+ * points at `./src/index.ts`), so every module in this package lives directly
+ * in `src/` and the package root is exactly one level up. `pkgPath()` is the
+ * single helper for resolving bundled assets against that root — the same base
+ * used for `presets/`, `templates/`, `package.json`, and `AGENT.md`.
+ */
+
+import * as path from "node:path";
+
+/**
+ * Resolve `segments` against the package root.
+ *
+ * Because the extension loads from `<pkg>/src/`, the package root is one level
+ * up from this module's directory. A wrong depth here would resolve inside
+ * `src/` and fail to find the bundled asset.
+ *
+ * @param segments - Path segments below the package root (e.g. `"presets"`, `"AGENT.md"`)
+ * @returns The absolute path to the bundled asset
+ */
+export function pkgPath(...segments: string[]): string {
+	return path.join(__dirname, "..", ...segments);
+}

package/src/templates.ts

@@ -27,6 +27,7 @@ import type { TaskTemplate, ThinkingLevel, SubagentPreset } from "./types";
 import { TEMPLATE_PARAM_RE, THINKING_LEVELS } from "./types";
 import type { Logger } from "./logging";
 import { parseFrontmatter, sanitizeFileName } from "./presets";
+import { pkgPath } from "./paths";
 
 // ---------------------------------------------------------------------------
 // Param extraction
@@ -373,7 +374,7 @@ export function getAllTemplates(
  * the extension's presets/ dir.
  */
 export function loadAllTemplates(cwd: string, log?: Logger, templatesDir?: string): TaskTemplate[] {
-	const builtinDir = templatesDir ?? path.join(__dirname, "..", "templates");
+	const builtinDir = templatesDir ?? pkgPath("templates");
 	return getAllTemplates(loadBuiltinTemplates(builtinDir, log), loadCustomTemplates(cwd, log));
 }