pi-subagents 0.69.0 → 0.70.1

package/package.json

@@ -1,27 +1,10 @@
 {
+  "type": "module",
   "name": "pi-subagents",
-  "version": "0.69.0",
+  "version": "0.70.1",
   "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
   "author": "Nico Bailon",
   "license": "MIT",
-  "type": "module",
-  "exports": {
-    ".": "./index.ts",
-    "./background-work": "./src/api/background-work.ts",
-    "./external-job-provider": "./src/api/external-job-provider.ts",
-    "./external-runs": "./src/api/external-runs.ts",
-    "./agents": "./src/api/agents.ts",
-    "./delegation": "./src/api/delegation.ts",
-    "./capability-ceiling": "./src/api/capability-ceiling.ts",
-    "./workflow-resources": "./src/api/workflow-resources.ts",
-    "./required-child-extensions": "./src/api/required-child-extensions.ts",
-    "./preflight": "./src/api/preflight.ts",
-    "./control-channel": "./src/api/control-channel.ts",
-    "./intercom-bridge": "./src/api/intercom-bridge.ts",
-    "./child-tool-plan": "./src/api/child-tool-plan.ts",
-    "./shared-types": "./src/api/shared-types.ts",
-    "./project-panes": "./src/api/project-panes.ts"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nicobailon/pi-subagents.git"
@@ -30,48 +13,15 @@
   "bugs": {
     "url": "https://github.com/nicobailon/pi-subagents/issues"
   },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-coding-agent",
-    "subagents",
-    "ai",
-    "agents",
-    "cli"
-  ],
   "bin": {
     "pi-subagents": "install.mjs"
   },
-  "files": [
-    "index.ts",
-    "src/**/*.ts",
-    "*.mjs",
-    "agents/",
-    "skills/**/*",
-    "prompts/**/*",
-    "docs/**/*",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "scripts": {
-    "build:pkg": "node scripts/build-package.mjs",
-    "pack:pkg": "npm run build:pkg && npm pack ./dist-pkg",
-    "typecheck": "tsc --noEmit",
-    "test": "npm run test:unit",
-    "test:unit": "node --experimental-strip-types --import ./test/support/isolated-temp-root.mjs --test test/unit/*.test.ts",
-    "test:integration": "node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/integration/*.test.ts",
-    "test:all": "npm run test:unit && npm run test:integration"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ],
-    "skills": [
-      "./skills"
-    ],
-    "prompts": [
-      "./prompts"
-    ]
+  "dependencies": {
+    "acorn": "8.18.0",
+    "jiti": "2.7.0",
+    "typebox": "1.1.38",
+    "undici": "8.10.0",
+    "yaml": "2.8.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
@@ -93,21 +43,87 @@
       "optional": true
     }
   },
-  "dependencies": {
-    "acorn": "8.18.0",
-    "jiti": "2.7.0",
-    "typebox": "1.1.38",
-    "undici": "8.10.0",
-    "yaml": "2.8.3"
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "subagents",
+    "ai",
+    "agents",
+    "cli"
+  ],
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./background-work": {
+      "types": "./src/api/background-work.d.ts",
+      "default": "./src/api/background-work.js"
+    },
+    "./external-job-provider": {
+      "types": "./src/api/external-job-provider.d.ts",
+      "default": "./src/api/external-job-provider.js"
+    },
+    "./external-runs": {
+      "types": "./src/api/external-runs.d.ts",
+      "default": "./src/api/external-runs.js"
+    },
+    "./agents": {
+      "types": "./src/api/agents.d.ts",
+      "default": "./src/api/agents.js"
+    },
+    "./delegation": {
+      "types": "./src/api/delegation.d.ts",
+      "default": "./src/api/delegation.js"
+    },
+    "./capability-ceiling": {
+      "types": "./src/api/capability-ceiling.d.ts",
+      "default": "./src/api/capability-ceiling.js"
+    },
+    "./workflow-resources": {
+      "types": "./src/api/workflow-resources.d.ts",
+      "default": "./src/api/workflow-resources.js"
+    },
+    "./required-child-extensions": {
+      "types": "./src/api/required-child-extensions.d.ts",
+      "default": "./src/api/required-child-extensions.js"
+    },
+    "./preflight": {
+      "types": "./src/api/preflight.d.ts",
+      "default": "./src/api/preflight.js"
+    },
+    "./control-channel": {
+      "types": "./src/api/control-channel.d.ts",
+      "default": "./src/api/control-channel.js"
+    },
+    "./intercom-bridge": {
+      "types": "./src/api/intercom-bridge.d.ts",
+      "default": "./src/api/intercom-bridge.js"
+    },
+    "./child-tool-plan": {
+      "types": "./src/api/child-tool-plan.d.ts",
+      "default": "./src/api/child-tool-plan.js"
+    },
+    "./shared-types": {
+      "types": "./src/api/shared-types.d.ts",
+      "default": "./src/api/shared-types.js"
+    },
+    "./project-panes": {
+      "types": "./src/api/project-panes.d.ts",
+      "default": "./src/api/project-panes.js"
+    }
   },
-  "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.81.0",
-    "@earendil-works/pi-ai": "0.81.0",
-    "@earendil-works/pi-tui": "0.81.0",
-    "@oxlint/plugins": "1.80.0",
-    "@types/node": "24.13.3",
-    "oxlint": "1.80.0",
-    "typescript": "5.9.3",
-    "@earendil-works/pi-coding-agent": "file:./test/fixtures/pi-coding-agent-shim"
+  "pi": {
+    "extensions": [
+      "./index.js"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ]
   }
 }

package/runner-peer-loader.mjs

@@ -2,8 +2,6 @@ import { pathToFileURL } from "node:url";
 
 let aliases = {};
 let nativeRunner = false;
-let compiledRunner = false;
-let packageRootUrl;
 const redirected = new Set([
 	"@earendil-works/pi-tui",
 ]);
@@ -11,14 +9,13 @@ const redirected = new Set([
 export function initialize(data) {
 	aliases = data?.aliases ?? {};
 	nativeRunner = data?.nativeRunner === true;
-	compiledRunner = data?.compiledRunner === true;
-	packageRootUrl = data?.packageRootUrl;
 }
 
 export function resolve(specifier, context, nextResolve) {
-	const packageImport = typeof packageRootUrl === "string" && context.parentURL?.startsWith(packageRootUrl) === true;
-	if (nativeRunner && (!compiledRunner || packageImport) ? aliases[specifier] : redirected.has(specifier) && aliases[specifier]) {
-		return nextResolve(pathToFileURL(aliases[specifier]).href, context);
+	const alias = nativeRunner ? aliases[specifier] : redirected.has(specifier) && aliases[specifier];
+	if (alias) {
+		const target = pathToFileURL(alias).href;
+		return nativeRunner ? { url: target, shortCircuit: true } : nextResolve(target, context);
 	}
 	return nextResolve(specifier, context);
 }

package/runner-peer-preload.mjs

@@ -3,9 +3,6 @@ import { pathToFileURL } from "node:url";
 
 const aliases = JSON.parse(process.env.JITI_ALIAS ?? "{}");
 const nativeRunner = process.env.PI_ASYNC_NATIVE_RUNNER === "1";
-const compiledRunner = process.env.PI_ASYNC_COMPILED_RUNNER === "1";
-// Pi's jiti loader owns aliases for external extensions; these hooks only supply peers to our compiled package.
-const packageRootUrl = new URL("./", import.meta.url).href;
 const redirected = new Set([
 	"@earendil-works/pi-tui",
 ]);
@@ -13,9 +10,10 @@ const redirected = new Set([
 if (typeof nodeModule.registerHooks === "function") {
 	nodeModule.registerHooks({
 		resolve(specifier, context, nextResolve) {
-			const packageImport = context.parentURL?.startsWith(packageRootUrl) === true;
-			if ((nativeRunner && (!compiledRunner || packageImport) ? aliases[specifier] : redirected.has(specifier) && aliases[specifier])) {
-				return nextResolve(pathToFileURL(aliases[specifier]).href, context);
+			const alias = nativeRunner ? aliases[specifier] : redirected.has(specifier) && aliases[specifier];
+			if (alias) {
+				const target = pathToFileURL(alias).href;
+				return nativeRunner ? { url: target, shortCircuit: true } : nextResolve(target, context);
 			}
 			try {
 				return nextResolve(specifier, context);
@@ -27,6 +25,6 @@ if (typeof nodeModule.registerHooks === "function") {
 	});
 } else {
 	nodeModule.register(new URL("./runner-peer-loader.mjs", import.meta.url), {
-		data: { aliases, nativeRunner, compiledRunner, packageRootUrl },
+		data: { aliases, nativeRunner },
 	});
 }

package/skills/pi-subagents/SKILL.md

@@ -101,6 +101,7 @@ For an authorized complex delegated workflow, read `prompting-and-roles.md` and
 - Keep the parent on the ordinary strong default model. Route workers/scouts to a fast capable tier, serious reviews to a strong tier, and top reasoning to bounded read-only critique.
 - Exact model names are deployment policy. Put them in user/project settings or profiles, not package guidance.
 - Give every child a compact meta-prompt checklist: objective; repo/cwd/ref; authority/edit boundary; relevant files/contracts and constraints; success/acceptance criteria; validation; expected output/report; and stop/ask conditions. See `references/prompting-and-roles.md`.
+- Before launching a writer for substantial mutation work, classify it as single-seam or multi-seam and partition multi-seam work across exclusive component owners, gates, and durable handoffs before an integration-only owner. See `references/multi-lane-orchestration.md`.
 - For mutation work, use an isolated lane/worktree when isolation, overlap, or concurrent juggling matters; keep one writer per cwd/worktree. See `references/multi-lane-orchestration.md` for lane mechanics.
 - Keep long/high-output validation out of chat: prefer `interactive_shell` dispatch/background monitors, bounded logs, or subagent-owned reports; return a concise summary plus report path unless same-turn output is required. Do not use `interactive_shell` as an implicit fallback for a failed `subagent` lane; see `references/execution-controls.md`.
 - Treat subagent workflow, child launch, prompt runtime, extension load, and child tooling setup failures as lane infrastructure blockers. Stop, report the exact failure and run/worktree state, verify a clean worktree or capture a partial diff, and use only a clear same-protocol retry or an owner-approved execution-mode fallback.

package/skills/pi-subagents/references/management-authoring-rpc.md

@@ -131,7 +131,7 @@ That is only a starting point. Omit `package` for the traditional unqualified ru
 
 `acceptance` is a single-agent launch default. Use a scalar level such as `checked` or an inline/block YAML map such as `{ level: "none", reason: "lightweight lookup" }`. An explicit tool-call value wins; scripted workflow child acceptance remains configured on the `runs.run` or `runs.all` item. Management create/update accepts the same policy object, and `acceptance: ""` clears the frontmatter default (`false` remains the deprecated disabled-policy shorthand).
 
-`acceptanceRole` is `read-only` or `writer` and controls automatic acceptance inference only. Explicit task mutation or no-edit intent wins; otherwise the role replaces agent-name guessing. Omission preserves the current name heuristics. The field does not grant or revoke tools. Management accepts `false` or an empty string to clear it.
+`acceptanceRole` is `read-only` or `writer` and controls automatic acceptance inference only. The structured role is authoritative; task wording and agent names do not escalate acceptance. Omission uses lightweight attestation. The field does not grant or revoke tools. Management accepts `false` or an empty string to clear it.
 
 `tools` is a strict child allowlist, not an extension loader. For a named extension tool, keep its registered name in `tools` and load its provider through normal Pi discovery, `extensions`, a path-like `tools` entry, or `subagentOnlyExtensions`. For example, pair `tools: read, fixture_search` with `subagentOnlyExtensions: ./tools/fixture-search.ts` when the provider should exist only in that agent's child sessions. The child now fails with the unavailable names and provider-loading guidance instead of silently continuing when a requested tool is absent; internal `structured_output` is allowed automatically when an output schema requires it.
 

package/skills/pi-subagents/references/multi-lane-orchestration.md

@@ -4,6 +4,14 @@ Use this reference when several independent tasks need coordinated workers, work
 
 Create lanes only after delegation is operator-authorized and each lane materially improves evidence, independent review, specialization, useful parallelism, or isolated execution. Do not manufacture parallelism: keep dependent work serial, and only split work when each lane has a distinct decision and useful output.
 
+## Mandatory implementation-topology preflight
+
+Before launching a writer for substantial mutation work, classify the implementation as **single-seam** or **multi-seam**. Two or more independently testable contracts or source boundaries make it multi-seam. One PR does not imply one writer, and the one-writer-per-worktree rule prevents concurrent ownership conflicts; it does not authorize an issue-wide commission.
+
+Record the classification and evidence on a lane board before writer launch. For multi-seam work, give each isolated component writer exclusive file or contract ownership and focused validation gates. Require every component to produce a committed or otherwise durable handoff, then start a separate integration-only owner after the component handoffs are ready. Mechanically reject and repartition a writer prompt if it owns all major outcomes across multiple independent boundaries.
+
+A single complete writer remains valid only when the board records evidence that the work is genuinely one seam or that splitting it would create overlapping ownership or artificial handoffs. This preflight must not manufacture parallelism: do not split tightly coupled work merely to increase the lane count.
+
 ## Lane board and authority
 
 Before multiple mutation-capable lanes start, record this board in the parent context:

package/skills/pi-subagents/references/prompting-and-roles.md

@@ -118,7 +118,7 @@ Use this after implementation when the user or applicable instructions request d
 
 ### Staged fix orchestration technique
 
-Use this when a broad diff has known reviewer findings across several items and the user wants the parent to “orchestrate subagents like a boss.” Keep the active worktree safe with a three-stage `workflowScript`:
+Use this when a broad diff has known reviewer findings across several items and the user wants the parent to “orchestrate subagents like a boss.” Keep mutation ownership explicit in the `workflowScript`:
 
 When staged seams are available, a low-tier writer should not receive the
 end-to-end issue. Use `runs.lanes` inside `workflowScript` to keep stages narrow:
@@ -126,44 +126,45 @@ a scout/red test, helper-only change, one render seam, validation, minimality
 challenge, or fresh review. Give the writer only its assigned implementation
 stage; keep sequencing and synthesis with the parent.
 
-1. A parallel read-only planning fanout, one reviewer per issue cluster. Each child inspects the real diff and returns exact files, line refs, proposed fixes, and focused validation. They must not edit.
-2. One writer worker. It receives the reviewer summaries as the awaited planning results (or their durable output paths) interpolated into its task, plus the parent’s accepted scope, stop rules, and verification contract. It is the only child allowed to edit the active worktree.
-3. A parallel read-only validation fanout. Validators inspect the worker diff from fresh context with distinct angles, report pass/fail, remaining blockers, and missing verification.
+1. A parallel read-only planning fanout, one reviewer per issue cluster or review angle. Each child inspects the real diff and returns exact files, line refs, proposed fixes, and focused validation. They must not edit.
+2. Classify the accepted fixes on the lane board before writer launch. If issue clusters are independently testable source or contract boundaries, use isolated component writers with exclusive file/contract ownership and focused gates. Each component must commit or produce another durable handoff; only after those handoffs are ready, start one integration-only owner.
+3. Use one writer for the complete fix only when the accepted fixes are one tightly coupled existing diff/seam and the lane board records evidence that splitting would create overlapping ownership or artificial handoffs. Give that writer the planning summaries, accepted scope, stop rules, and verification contract.
+4. Run fresh-context, read-only validation against the integrated or single-seam result. Validators use distinct angles and report pass/fail, remaining blockers, and missing verification.
 
 Prefer `async: true`, `context: "fresh"` for reviewers/validators, `outputMode: "file-only"` for large summaries, and per-stage output names that will not collide. Use stable `runs` keys plus `phase` and `label` on each launch item to make async status readable, and hold each awaited result in an ordinary JavaScript variable when a later step needs that specific result — interpolate it (or the durable output path you declared for that child) into the later task text instead of passing a whole aggregate blob. Use this pattern instead of launching several writer workers into a dirty worktree. Include non-blocking suggestions in the writer prompt only when they are small, safe, and do not expand product scope; otherwise record them as deferred.
 
 When one child returns a structured target list, use ordinary JavaScript to validate/filter it and map bounded entries into `runs.all`; do not use the removed chain fanout DSL.
 
-Example shape:
+Single-seam example shape (the lane board records that these are review angles on one tightly coupled deployment-lifecycle diff, not independent implementation contracts):
 
 ```typescript
 subagent({
   async: true,
   context: "fresh",
   workflowScript: `
-    // Stage 1: parallel read-only planning fanout (stable keys, one per issue cluster)
+    // Stage 1: parallel read-only review angles on one recorded single seam
     const plans = await runs.all([
-      { key: "deploy-plan", agent: "reviewer", phase: "Planning", label: "Deploy docs", task: "Plan fixes for deploy docs/workflow. Inspect the current diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/deploy.md", outputMode: "file-only" },
-      { key: "scheduler-plan", agent: "reviewer", phase: "Planning", label: "Scheduler contract", task: "Plan fixes for scheduler contract. Inspect the current diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/scheduler.md", outputMode: "file-only" },
-      { key: "sandbox-plan", agent: "reviewer", phase: "Planning", label: "Sandbox/security", task: "Plan fixes for sandbox/security. Inspect the current diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/sandbox.md", outputMode: "file-only" }
+      { key: "correctness-plan", agent: "reviewer", phase: "Planning", label: "Review lifecycle correctness", task: "Plan correctness fixes for the same deployment-lifecycle diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/correctness.md", outputMode: "file-only" },
+      { key: "regression-plan", agent: "reviewer", phase: "Planning", label: "Review lifecycle regressions", task: "Plan regression coverage for the same deployment-lifecycle diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/regressions.md", outputMode: "file-only" },
+      { key: "minimality-plan", agent: "reviewer", phase: "Planning", label: "Review lifecycle minimality", task: "Plan minimality fixes for the same deployment-lifecycle diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/minimality.md", outputMode: "file-only" }
     ]);
 
-    // Stage 2: single writer — the only child allowed to edit the active worktree.
+    // Stage 2: one writer for this lane-board-recorded single seam.
     // Under outputMode "file-only" the awaited .output is the saved-output
     // reference, so pass those managed artifact references to the writer.
     const worker = await runs.run("apply-fixes", {
       agent: "worker",
       phase: "Implementation",
       label: "Apply accepted fixes",
-      task: "Apply only the accepted fixes from these planning summaries. You are the sole writer for the active worktree. Run focused validation and report changed files, commands, failures, and remaining issues.\\n\\nDeploy plan: " + plans[0].output + "\\n\\nScheduler plan: " + plans[1].output + "\\n\\nSandbox plan: " + plans[2].output,
+      task: "Apply only the accepted fixes to the one deployment-lifecycle seam. The lane board records that splitting this existing diff would create overlapping ownership. You are the sole writer for this seam. Run focused validation and report changed files, commands, failures, and remaining issues.\\n\\nCorrectness plan: " + plans[0].output + "\\n\\nRegression plan: " + plans[1].output + "\\n\\nMinimality plan: " + plans[2].output,
       output: "worker/fixes.md",
       outputMode: "file-only"
     });
 
     // Stage 3: parallel read-only validation fanout
     const validations = await runs.all([
-      { key: "validate-deploy-scheduler", agent: "reviewer", phase: "Validation", label: "Deploy/scheduler validation", task: "Validate the post-worker diff for deploy and scheduler fixes. Start from the worker result: " + worker.output + ". Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/deploy-scheduler.md", outputMode: "file-only" },
-      { key: "validate-sandbox", agent: "reviewer", phase: "Validation", label: "Sandbox validation", task: "Validate the post-worker diff for sandbox/security fixes. Start from the worker result: " + worker.output + ". Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/sandbox.md", outputMode: "file-only" }
+      { key: "validate-behavior", agent: "reviewer", phase: "Validation", label: "Validate lifecycle behavior", task: "Validate behavior in the post-worker deployment-lifecycle diff. Start from the worker result: " + worker.output + ". Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/behavior.md", outputMode: "file-only" },
+      { key: "validate-minimality", agent: "reviewer", phase: "Validation", label: "Validate lifecycle minimality", task: "Validate minimality in the same post-worker deployment-lifecycle diff. Start from the worker result: " + worker.output + ". Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/minimality.md", outputMode: "file-only" }
     ]);
 
     return { worker: worker.output, validations: validations.map(v => v.output) };
@@ -186,7 +187,7 @@ and user/project agents override builtins with the same name.
 | `oracle` | Rare hard-decision/root-cause escalation | top-reasoning critic tier, bounded read-only; high thinking escalation only | Advisory trajectory review, not routine code review |
 | `advisor` | Compatibility alias for `oracle` | top-reasoning critic tier, bounded read-only; high thinking escalation only | Same advisory escalation role as `oracle` |
 
-Builtin `worker` and `delegate` use strict tool allowlists and do not inherit ambient parent extension tools. To give a child an extension tool, name it in `tools` and load its provider via `extensions`, a path-like `tools` entry, or `subagentOnlyExtensions`. Custom agents without an `extensions` field follow `subagents.defaultExtensions` when set.
+Builtin `worker` and `delegate` use strict tool allowlists and do not inherit ambient parent extension tools. To give a child an extension tool, name it in `tools` and load its provider via `extensions`, a path-like `tools` entry, or `subagentOnlyExtensions`. Agents without the corresponding field follow `subagents.defaultExtensions` or the ambient-preserving `subagents.defaultSubagentOnlyExtensions` when set.
 
 Builtin agents inherit the current Pi default model unless a run, user setting, project setting, or `subagents.defaultModel` overrides `model`. The table records recommended tier routing, not shipped hard defaults; explicit run, user, or project settings still win. Keep the parent/orchestrator on the ordinary strong default model unless parent/user policy says otherwise. Override builtin defaults before copying full agent files when a small tweak is enough.
 
@@ -294,6 +295,6 @@ If a provider rejects model IDs with thinking suffixes, use
 builtin thinking defaults globally. A higher-precedence per-agent `thinking`
 override can opt one builtin back in or replace custom-agent frontmatter thinking.
 
-Set `subagents.defaultExtensions` to give agents without an `extensions` field a shared child extension allowlist. Omit it to preserve ambient extension discovery, set it to `[]` to disable ambient extensions by default, or use `agentOverrides.<name>.extensions` for one agent. A matching override replaces custom-agent frontmatter for that field.
+Set `subagents.defaultExtensions` to give agents without an `extensions` field a shared child extension allowlist. Omit it to preserve ambient extension discovery, set it to `[]` to disable ambient extensions by default, or use `agentOverrides.<name>.extensions` for one agent. Set `subagents.defaultSubagentOnlyExtensions` to add shared child-only paths without disabling ambient discovery. For either field, explicit frontmatter suppresses the default and a matching override replaces or false-clears it; lists are not combined.
 
 Tool description modes live in `~/.pi/agent/extensions/subagent/config.json`, not `subagents` settings. The default uses split prompt metadata: a short tool description plus active `promptSnippet` and `promptGuidelines`. Set `toolDescriptionMode` to `full` or `compact` to force one description string, or `custom` to read `subagent-tool-description.md` from the project config dir or agent dir; invalid custom files fall back to full mode and the safety guidance is still appended.

package/src/agents/advertised-agent-prompt.d.ts

@@ -0,0 +1,8 @@
+import type { ResolvedSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
+import type { AgentConfig } from "./agents.ts";
+export declare function buildAdvertisedAgentPrompt(agents: readonly AgentConfig[], capabilityCeiling?: ResolvedSubagentCapabilityCeiling): string | undefined;
+export declare function appendAdvertisedAgentPrompt(systemPrompt: string, advertisedPrompt: string | undefined): string;
+export declare function appendAdvertisedAgentPrompt(systemPrompt: string[], advertisedPrompt: string | undefined): string[];
+export declare function appendAdvertisedAgentPrompt(systemPrompt: undefined, advertisedPrompt: string | undefined): string | undefined;
+export declare function appendAdvertisedAgentPrompt(systemPrompt: string | string[] | undefined, advertisedPrompt: string | undefined): string | string[] | undefined;
+//# sourceMappingURL=advertised-agent-prompt.d.ts.map

package/src/agents/advertised-agent-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advertised-agent-prompt.d.ts","sourceRoot":"","sources":["../../../src/agents/advertised-agent-prompt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,sCAAsC,CAAC;AAE9F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAwB/C,wBAAgB,0BAA0B,CACzC,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,iBAAiB,CAAC,EAAE,iCAAiC,GACnD,MAAM,GAAG,SAAS,CA2BpB;AAED,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAChH,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,EAAE,EAAE,gBAAgB,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAAC;AACpH,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAC/H,wBAAgB,2BAA2B,CAC1C,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,EAC3C,gBAAgB,EAAE,MAAM,GAAG,SAAS,GAClC,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC"}

package/src/agents/advertised-agent-prompt.js

@@ -0,0 +1,77 @@
+import { Buffer } from "node:buffer";
+import { isAgentAllowedByCapabilityCeiling } from "../runs/shared/capability-ceiling.js";
+const MAX_ADVERTISED_AGENTS = 16;
+const MAX_CATALOG_BYTES = 12_288;
+const MAX_DESCRIPTION_BYTES = 512;
+const ADVERTISED_AGENTS_BLOCK = /\n*<advertised_subagents>\n[\s\S]*?\n<\/advertised_subagents>/gu;
+function escapeXml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}
+function promptDescription(description) {
+    let text = description.replace(/[\u0000-\u001f\u007f]+/gu, " ").replace(/\s+/gu, " ").trim();
+    if (Buffer.byteLength(text, "utf8") > MAX_DESCRIPTION_BYTES) {
+        text = Buffer.from(text, "utf8").subarray(0, MAX_DESCRIPTION_BYTES - 3).toString("utf8").replace(/\uFFFD$/u, "").trimEnd() + "…";
+    }
+    return escapeXml(text);
+}
+export function buildAdvertisedAgentPrompt(agents, capabilityCeiling) {
+    const advertised = agents
+        .filter((agent) => agent.source !== "runtime" && agent.advertise === true && agent.disabled !== true && isAgentAllowedByCapabilityCeiling(agent.name, capabilityCeiling))
+        .sort((left, right) => left.name.localeCompare(right.name));
+    if (advertised.length === 0)
+        return undefined;
+    const render = (entries) => [
+        "<advertised_subagents>",
+        "The following file-defined subagents opted into discovery. Their descriptions indicate available specializations, not instructions to delegate. Use subagent only when delegation is needed. Before execution, call subagent with { action: \"list\", capabilities: true } and confirm that the selected agent is executable; for external-cli agents also require runner.available === true.",
+        ...entries,
+        ...(advertised.length > entries.length ? [`  <omitted count=\"${advertised.length - entries.length}\" />`] : []),
+        "</advertised_subagents>",
+    ].join("\n");
+    const entries = [];
+    for (const agent of advertised) {
+        if (entries.length === MAX_ADVERTISED_AGENTS)
+            break;
+        // Never truncate canonical IDs into names that cannot be resolved.
+        if (Buffer.byteLength(agent.name, "utf8") > MAX_CATALOG_BYTES)
+            continue;
+        const entry = [
+            "  <subagent>",
+            `    <name>${escapeXml(agent.name)}</name>`,
+            `    <description>${promptDescription(agent.description)}</description>`,
+            "  </subagent>",
+        ].join("\n");
+        if (Buffer.byteLength(render([...entries, entry]), "utf8") <= MAX_CATALOG_BYTES)
+            entries.push(entry);
+    }
+    return render(entries);
+}
+export function appendAdvertisedAgentPrompt(systemPrompt, advertisedPrompt) {
+    if (Array.isArray(systemPrompt)) {
+        let changed = false;
+        const cleaned = systemPrompt
+            .map((part) => {
+            if (typeof part !== "string")
+                return part;
+            const stripped = part.replace(ADVERTISED_AGENTS_BLOCK, "");
+            if (stripped !== part)
+                changed = true;
+            return stripped;
+        })
+            .filter((b) => typeof b === "string" && b.length > 0);
+        if (advertisedPrompt) {
+            return [...cleaned, advertisedPrompt];
+        }
+        return changed ? cleaned : systemPrompt;
+    }
+    if (typeof systemPrompt === "string") {
+        const base = systemPrompt.replace(ADVERTISED_AGENTS_BLOCK, "");
+        return advertisedPrompt ? (base.trim() ? `${base.trimEnd()}\n\n${advertisedPrompt}` : advertisedPrompt) : base;
+    }
+    return advertisedPrompt;
+}
+//# sourceMappingURL=advertised-agent-prompt.js.map

package/src/agents/advertised-agent-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advertised-agent-prompt.js","sourceRoot":"","sources":["../../../src/agents/advertised-agent-prompt.ts"],"names":[],"mappings":"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"}

package/src/agents/agent-management.d.ts

@@ -0,0 +1,27 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type AgentConfig } from "./agents.ts";
+import type { Details, ExtensionConfig } from "../shared/types.ts";
+import { type RuntimeAgentOwner } from "./runtime-agent-registry.ts";
+type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry"> & {
+    model?: ExtensionContext["model"];
+    config?: ExtensionConfig;
+    currentSessionId?: string;
+    runtimeAgentOwner?: RuntimeAgentOwner;
+    onAgentsChanged?: () => void;
+};
+interface ManagementParams {
+    action?: string;
+    agent?: string;
+    agentScope?: unknown;
+    capabilities?: unknown;
+    config?: unknown;
+}
+export declare function editableAgentConfig(agent: AgentConfig): AgentConfig;
+export declare function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<string, unknown>): Set<string>;
+export declare function handleList(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details>;
+export declare function handleCreate(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details>;
+export declare function handleUpdate(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details>;
+export declare function handleManagementAction(action: string, params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details>;
+export {};
+//# sourceMappingURL=agent-management.d.ts.map

package/src/agents/agent-management.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-management.d.ts","sourceRoot":"","sources":["../../../src/agents/agent-management.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EACN,KAAK,WAAW,EAiBhB,MAAM,aAAa,CAAC;AAcrB,OAAO,KAAK,EAAkE,OAAO,EAAE,eAAe,EAAoB,MAAM,oBAAoB,CAAC;AAIrJ,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAKzF,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,eAAe,CAAC,GAAG;IAAE,KAAK,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC;AAE3O,UAAU,gBAAgB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAoMD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CA8EnE;AAWD,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAsD7G;AA8jBD,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,iBAAiB,GAAG,eAAe,CAAC,OAAO,CAAC,CAuCrG;AAmID,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,iBAAiB,GAAG,eAAe,CAAC,OAAO,CAAC,CAiDvG;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,iBAAiB,GAAG,eAAe,CAAC,OAAO,CAAC,CA+DvG;AAoJD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,iBAAiB,GAAG,eAAe,CAAC,OAAO,CAAC,CAcjI"}