pi-herdr-subagents-lite 0.2.0 → 0.3.0

package/README.md

@@ -9,7 +9,7 @@ Experimental; compatibility across versions is not promised. Exact behavior live
 ## Features
 
 - **Separate process, human takeover**: each subagent is its own pi process in a herdr pane. Same cwd as the parent opens a tab in the same workspace, otherwise a new workspace. Switch into the pane and take over at any time.
-- **Profile layers**: Markdown + frontmatter under `<agent-dir>/pi-herdr-subagents-lite/profiles/`, plus a project layer under `.pi/pi-herdr-subagents-lite/profiles/` that wins on the same name.
+- **Profile layers**: Markdown + frontmatter under `<agent-dir>/pi-herdr-subagents-lite/profiles/`, plus a project layer under `.pi/pi-herdr-subagents-lite/profiles/` that wins on the same `name`.
 - **Async, merged results**: `run` returns at once. Each finished child reports one `subagent_result` message; results inside `aggregateWindowMs` merge into one. Oversize results go to an artifact file.
 - **Questions stay with the human**: a child prompt marks its pane `herdr:blocked` and nothing goes to the parent. The human answers in the child pane; no model relays the answer.
 - **No nesting by default, no sandbox**: child tool sets drop this tool unless the profile names it. The profile picks tools; the extension does not restrict writes.
@@ -36,7 +36,7 @@ Upgrade with `pi update --extensions`, remove with `pi remove <source>`. After a
 ## Quick start
 
 1. Start `pi` in a herdr pane.
-2. Write a profile (next section); the file name without `.md` is the name `run` takes.
+2. Write a profile (next section); its frontmatter `name` is the key `run` takes. The file name is not used for lookup.
 3. Ask the model to call the tool:
 
 ```json
@@ -51,12 +51,12 @@ It returns `{"state":"running",...}`, runs in its own tab, and a `[subagent expl
 
 ## Profile
 
-Global profiles live in `<agent-dir>/pi-herdr-subagents-lite/profiles/*.md`, project profiles in `.pi/pi-herdr-subagents-lite/profiles/*.md` (read once the project is trusted); the project wins on the same name.
+Global profiles live in `<agent-dir>/pi-herdr-subagents-lite/profiles/*.md`, project profiles in `.pi/pi-herdr-subagents-lite/profiles/*.md` (read once the project is trusted); the project wins on the same `name`.
 
 ```markdown
 ---
-# Listed as "file (name)"; run takes the file name
-name: Explore
+# Key run takes; keep it equal to the file name
+name: explore
 description: "Read-only research: read code, answer questions, change nothing"
 
 # Omit to inherit from the parent
@@ -84,9 +84,9 @@ disable-model-invocation: false
 You are a read-only explorer. Answer with file paths and line numbers.
 ```
 
-Defaults and error codes: [contract section 2](docs/specs/0001-v1-contract.md#2-profile). A file that fails to parse stays out of the list; `run` returns `profile_invalid` with the file, field and reason.
+Defaults and error codes: [contract section 2](docs/specs/0001-v1-contract.md#2-profile). A file without `name`, or with an invalid field, stays out of the list; duplicate names in one layer are all rejected. `run` returns `profile_invalid` with the file, field and reason.
 
-A bundled example ships with the extension. Loading reads `profiles/*.md` only and the example is written only when missing, so copy it one level up:
+A bundled example ships with the extension; its file name and `name` are both `domain`. Loading reads `profiles/*.md` only and the example is written only when missing, so copy it one level up:
 
 ```bash
 cd ~/.pi/agent/pi-herdr-subagents-lite/profiles && cp examples/domain.md domain.md
@@ -176,6 +176,7 @@ All docs are in Chinese.
 - [ARCHITECTURE](docs/ARCHITECTURE.md): module boundaries, dependency direction, test seams
 - [GLOSSARY](docs/GLOSSARY.md): the only source for terms
 - [Modules](docs/modules/): usage and trade-offs per module
+- [ADR](docs/decisions/): decisions and rejected proposals, with reasons
 
 ## Development
 

package/README.zh-CN.md

@@ -9,7 +9,7 @@ pi 扩展：让子代理作为独立 pi 进程跑在 herdr pane 里。一个工
 ## 功能
 
 - **独立进程，可人工接管**：每个子代理是 herdr pane 里独立的 pi 进程。cwd 与父相同则同 workspace 新开 tab，否则新建 workspace。随时切进去接管。
-- **两层 profile**：Markdown + frontmatter，全局 `<agent-dir>/pi-herdr-subagents-lite/profiles/`，项目层 `.pi/pi-herdr-subagents-lite/profiles/`，同名时项目层覆盖。
+- **两层 profile**：Markdown + frontmatter，全局 `<agent-dir>/pi-herdr-subagents-lite/profiles/`，项目层 `.pi/pi-herdr-subagents-lite/profiles/`，`name` 相同时项目层覆盖。
 - **异步、可合并的结果**：`run` 立即返回。每个子代理收工时投一条 `subagent_result`；落在 `aggregateWindowMs` 内的结果合并成一条。超长结果落 artifact 文件。
 - **反问留在人这边**：子代理弹出对话框时只发出 `herdr:blocked` 事件，父侧什么也收不到。人在子 pane 里回答，不经模型转达。
 - **默认不嵌套，也不是沙箱**：子代理的工具集默认去掉本工具，profile 里点名才授予。工具由 profile 决定，扩展不限制写操作。
@@ -36,7 +36,7 @@ pi -e /path/to/pi-herdr-subagents-lite/src/index.ts        # 只对当前进程
 ## 快速开始
 
 1. 在 herdr pane 里启动 `pi`。
-2. 写一个 profile（下一节）；文件名去掉 `.md` 就是 `run` 的寻址名。
+2. 写一个 profile（下一节）；frontmatter `name` 就是 `run` 的寻址名，文件名不参与查找。
 3. 让模型调用工具：
 
 ```json
@@ -51,12 +51,12 @@ pi -e /path/to/pi-herdr-subagents-lite/src/index.ts        # 只对当前进程
 
 ## Profile
 
-全局 profile 在 `<agent-dir>/pi-herdr-subagents-lite/profiles/*.md`，项目 profile 在 `.pi/pi-herdr-subagents-lite/profiles/*.md`（项目受信任后才读）；同名时项目覆盖全局。
+全局 profile 在 `<agent-dir>/pi-herdr-subagents-lite/profiles/*.md`，项目 profile 在 `.pi/pi-herdr-subagents-lite/profiles/*.md`（项目受信任后才读）；`name` 相同时项目覆盖全局。
 
 ```markdown
 ---
-# 列表写作「文件名 (显示名)」；run 取文件名
-name: Explore
+# run 的寻址名；建议与文件名保持一致
+name: explore
 description: 只读调研：读代码、回答问题，不改动任何文件
 
 # 省略即继承父会话
@@ -84,9 +84,9 @@ disable-model-invocation: false
 你是一名只读探索者，回答时给出文件路径与行号。
 ```
 
-字段默认值与错误码见 [契约 §2](docs/specs/0001-v1-contract.md#2-profile)。解析失败的文件不进列表；对它 `run` 返回 `profile_invalid`，带文件、字段与原因。
+字段默认值与错误码见 [契约 §2](docs/specs/0001-v1-contract.md#2-profile)。没写 `name`、字段非法或同层同名的文件都不进列表；对它 `run` 返回 `profile_invalid`，带文件、字段与原因。
 
-扩展自带一个示例 profile。加载只读 `profiles/*.md`，示例也只在缺失时写入，所以复制一层上去即可：
+扩展自带一个示例 profile，文件名和 `name` 都是 `domain`。加载只读 `profiles/*.md`，示例也只在缺失时写入，所以复制一层上去即可：
 
 ```bash
 cd ~/.pi/agent/pi-herdr-subagents-lite/profiles && cp examples/domain.md domain.md
@@ -174,6 +174,7 @@ cd ~/.pi/agent/pi-herdr-subagents-lite/profiles && cp examples/domain.md domain.
 - [ARCHITECTURE](docs/ARCHITECTURE.md) — 模块边界与 seam，改结构前看
 - [GLOSSARY](docs/GLOSSARY.md) — 术语唯一来源，命名前看
 - [模块](docs/modules/) — 各模块的用法与取舍
+- [ADR](docs/decisions/) — 已决选型与理由，改设计前扫一遍
 
 ## 开发
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-subagents-lite",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Run pi subagents in herdr panes.",
   "type": "module",
   "license": "MIT",

package/src/profile/examples.ts

@@ -1,8 +1,8 @@
 export const EXAMPLE_PROFILE_FILE = "domain.md";
 
 export const EXAMPLE_PROFILE = `---
-# Copy this file to profiles/domain.md to use it. The file name is what \`run\` takes.
-name: Domain
+# Copy this file to profiles/domain.md to use it. \`name\` is what \`run\` takes.
+name: domain
 description: Take one domain of work into a fresh context. Invoke by name.
 
 # User-invoked: hidden from the tool guidelines, so only an explicit run uses it.

package/src/profile/frontmatter.ts

@@ -8,7 +8,6 @@ export type SystemPromptMode = (typeof SYSTEM_PROMPT_MODES)[number];
 
 export interface Profile {
   name: string;
-  displayName: string;
   description: string;
   body: string;
   model: string | undefined;
@@ -48,6 +47,24 @@ function complain(fields: Fields, field: string, reason: string) {
   fields.problems.push({ name: fields.name, file: fields.file, field, reason });
 }
 
+export function nameField(fields: Fields): string | undefined {
+  const value = fields.raw.name;
+  if (value === undefined) {
+    complain(fields, "name", "required");
+    return undefined;
+  }
+  if (typeof value !== "string") {
+    complain(fields, "name", `expected string, got ${typeName(value)}`);
+    return undefined;
+  }
+  const name = value.trim();
+  if (name === "") {
+    complain(fields, "name", "expected a non-empty name");
+    return undefined;
+  }
+  return name;
+}
+
 export function stringField(fields: Fields, key: string): string | undefined {
   const value = fields.raw[key];
   if (value === undefined) {

package/src/profile/layers.ts

@@ -7,6 +7,7 @@ import {
   booleanField,
   enumField,
   type Fields,
+  nameField,
   type Profile,
   type ProfileProblem,
   SYSTEM_PROMPT_MODES,
@@ -27,24 +28,27 @@ export interface ProfileSources {
 }
 
 function parseProfile(file: string, source: string): { profile?: Profile; problems: ProfileProblem[] } {
-  const name = basename(file, ".md");
   let frontmatter: unknown;
   let body: string;
   try {
     ({ frontmatter, body } = parseFrontmatter(source));
   } catch (error) {
     const reason = error instanceof Error ? error.message : "parse failed";
-    return { problems: [{ name, file, field: "frontmatter", reason }] };
+    return { problems: [{ name: basename(file, ".md"), file, field: "frontmatter", reason }] };
   }
   if (!isRaw(frontmatter)) {
-    return { problems: [{ name, file, field: "frontmatter", reason: "expected a mapping" }] };
+    return { problems: [{ name: basename(file, ".md"), file, field: "frontmatter", reason: "expected a mapping" }] };
   }
 
   const problems: ProfileProblem[] = [];
-  const fields: Fields = { raw: frontmatter, name, file, problems };
+  const fields: Fields = { raw: frontmatter, name: basename(file, ".md"), file, problems };
+  const name = nameField(fields);
+  if (name === undefined) {
+    return { problems };
+  }
+  fields.name = name;
   const profile: Profile = {
     name,
-    displayName: stringField(fields, "name") ?? name,
     description: stringField(fields, "description") ?? "",
     body,
     model: stringField(fields, "model"),
@@ -69,7 +73,7 @@ function readProfilesDir(dir: string): ProfileCatalog {
     throw error;
   }
 
-  const profiles: Profile[] = [];
+  const parsed: Array<{ profile: Profile; file: string }> = [];
   const problems: ProfileProblem[] = [];
   for (const entry of entries.sort()) {
     const file = join(dir, entry);
@@ -81,12 +85,41 @@ function readProfilesDir(dir: string): ProfileCatalog {
       problems.push({ name: basename(entry, ".md"), file, field: "file", reason });
       continue;
     }
-    const parsed = parseProfile(file, source);
-    if (parsed.profile) {
-      profiles.push(parsed.profile);
+    const result = parseProfile(file, source);
+    if (result.profile) {
+      parsed.push({ profile: result.profile, file });
+    }
+    problems.push(...result.problems);
+  }
+
+  const byName = new Map<string, Array<{ profile: Profile; file: string }>>();
+  for (const entry of parsed) {
+    const group = byName.get(entry.profile.name);
+    if (group) {
+      group.push(entry);
+    } else {
+      byName.set(entry.profile.name, [entry]);
+    }
+  }
+
+  const profiles: Profile[] = [];
+  for (const [name, group] of byName) {
+    const [only] = group;
+    if (only && group.length === 1) {
+      profiles.push(only.profile);
+      continue;
+    }
+    for (const entry of group) {
+      const others = group.filter((other) => other.file !== entry.file).map((other) => other.file);
+      problems.push({
+        name,
+        file: entry.file,
+        field: "name",
+        reason: `duplicate profile name; also in ${others.join(", ")}`,
+      });
     }
-    problems.push(...parsed.problems);
   }
+  profiles.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
   return { profiles, problems };
 }
 

package/src/run/resolve.ts

@@ -2,8 +2,7 @@ import type { Profile, ProfileCatalog } from "../profile/index.ts";
 import { ToolError } from "./errors.ts";
 
 export function profileLabel(profile: Profile): string {
-  const label = profile.displayName === profile.name ? profile.name : `${profile.name} (${profile.displayName})`;
-  return profile.description === "" ? label : `${label} — ${profile.description}`;
+  return profile.description === "" ? profile.name : `${profile.name} — ${profile.description}`;
 }
 
 export function resolveProfile({ profiles, problems }: ProfileCatalog, name: string): Profile {