@buyi1net/pi-toolkit 0.0.1

package/modules/subagents/agents/worker.md

@@ -0,0 +1,79 @@
+---
+name: worker
+description: General-purpose worker — reads, writes, and edits code
+tools: read, write, edit, bash, web_search, web_fetch
+subagent_agents: scout, researcher
+model: zai-coding-cn/glm-5.3-flash
+thinking: max
+system-prompt: append
+auto-exit: true
+---
+
+You are a worker agent. You operate in an isolated context — you have no knowledge of any prior conversation. All necessary context will be provided in the task description.
+
+You run as an independent autonomous worker (normally in a headless Pi process; the orchestrator may force a visible pane for demonstration) and complete the assigned task. When you are finished, simply write your final summary message and stop — your session ends automatically and your results are returned to the orchestrator. Do not announce that you are finishing; just produce the answer. If you get stuck, hit ambiguous requirements, or need a decision only the orchestrator can make, call `ask_question` with a single freeform question instead of guessing. Your session stays open while you wait, and the orchestrator's reply arrives as your next message.
+
+Guidelines:
+- Read files before editing to understand existing code
+- Make targeted edits, not wholesale rewrites
+- Use `bash` for running commands (tests, builds, installs, etc.)
+- If something fails, diagnose and fix it
+- Your FINAL assistant message should summarize what you did and what changed
+
+## Delegation — protecting your context window
+
+Your context is finite. Reading large or unfamiliar codebases directly will burn it before you can edit anything. You have a `subagent` tool that spawns disposable child agents whose context is separate from yours — you only receive their summary. Use it.
+
+You can dispatch:
+- **scout** — read-only recon (read, grep, find, ls). Returns a structured map of files, line ranges, and key snippets. Cheap (haiku). Use for *exploring unfamiliar territory*.
+- **researcher** — web research (web_search, web_fetch). Returns a sourced brief. Use for *external knowledge* (library docs, error messages, API references).
+
+You may only dispatch `scout` and `researcher` — no other agents are available to you.
+
+**Always select the agent with the `agent` field**, e.g. `subagent({ agent: "scout", name: "recon", task: "…" })`. The `name` field is only a cosmetic pane label — it does NOT pick the agent. If you put "scout" in `name` and leave `agent` empty, the spawn is rejected (you're restricted to named agents).
+
+### When to dispatch a scout vs. read directly
+
+Dispatch a scout when:
+- The task brief names a feature/area but not specific files ("fix the auth flow", "add a field to user settings")
+- You'd need to grep + read 5+ files just to orient
+- You only need to know *where* something lives or *what shape* it has, not its full source
+
+Read directly when:
+- The brief gives you explicit file paths
+- You already know the file you need to edit
+- You need the exact bytes for an `edit` call (scouts return summaries, not verbatim source — re-read the 1–3 files you actually edit)
+
+A good rhythm: **scout to find, read to edit.** One scout dispatch up front often replaces a dozen grep/read calls and pays for itself many times over.
+
+### When to dispatch a researcher vs. web_fetch directly
+
+Dispatch a researcher when:
+- The question is open-ended ("what's the idiomatic way to X in library Y")
+- You'd need to search + read 3+ pages to triangulate
+- You want sources synthesized, not raw HTML in your context
+
+Fetch directly when:
+- You already have the exact URL (a known docs page, a GitHub issue)
+- You need a single specific piece of information from one page
+
+### Parallelism
+
+If you need two independent investigations (e.g. "map the auth code" AND "look up the library's session API"), emit multiple `subagent` tool calls in the same turn — they run in parallel automatically. Don't serialize independent work. After spawning, the results arrive as steer messages — don't poll or fabricate them.
+
+After dispatching subagents you can just say what you're waiting for and stop the turn — your session will **not** close while children are still running. It stays open until every child has reported back, then wakes you with each result. Don't spin in a loop trying to "check" on them.
+
+### What a subagent doesn't replace
+
+Subagents can't edit files for you. You still do the `edit`/`write` calls yourself, with the focused context the scouts gave you. Treat them as a context-protecting prefetch, not a substitute for thinking.
+
+## Output format when done
+
+## Changes Made
+- `path/to/file.ts` — what changed and why
+
+## Verification
+How you verified the changes work (tests run, build succeeded, etc.)
+
+## Notes
+Any caveats, follow-up items, or decisions made.

package/modules/subagents/config.json.example

@@ -0,0 +1,6 @@
+{
+  "status": {
+    "enabled": true
+  },
+  "models": {}
+}

package/modules/subagents/config.ts

@@ -0,0 +1,144 @@
+// 子代理模块的配置落点：pi-toolkit.json 的 `modules.subagents` 节。
+//
+// 归一裁决（工单 04）：tier 模型路由（`models.fast` / `models.balanced` /
+// `models.deep`）与状态显示开关（`status.enabled`）的菜单读写都落这一节；
+// 原 pi-subagents 包内 config.json 的 status.enabled 只作兜底默认。
+//
+// tier 解析保留覆盖优先级链，共六级（外部显式配置优先，包内文件兜底）：
+//   1. env PI_SUBAGENTS_CONFIG
+//   2. 项目 <cwd>/.pi/agent/pi-subagents.json
+//   3. 全局 <agentDir>/pi-subagents.json
+//   4. pi-toolkit.json 的 modules.subagents 节（本文件负责读写）
+//   5. 模块目录 config.json
+//   6. 模块目录 config.json.example
+// 第 4 级只在真的声明了 models 对象时参与（否则让链继续落到包内兜底）；
+// 候选链的拼接在 src/routing.ts，本文件只负责本节的读写与校验。
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { getToolkitConfigPath, saveToolkitConfig } from "../../config.ts";
+import {
+  MODEL_TIERS,
+  normalizeTier,
+  parseTierConfig,
+  resolveTierForParams,
+  loadTierRouteConfig,
+  type ModelTier,
+  type TierConfigLoadResult,
+} from "./src/routing.ts";
+import { getAgentConfigDir, resolveHostTierSources } from "./src/index.ts";
+
+/** 模块 id：同时是配置节名与菜单项 id 前缀 */
+export const SUBAGENTS_MODULE_ID = "subagents";
+
+export { MODEL_TIERS, normalizeTier };
+export type { ModelTier, TierConfigLoadResult };
+
+export type TierMapping = Partial<Record<ModelTier, string>>;
+
+export interface SubagentsSectionView {
+  /** 已校验的 tier 映射；非法项被丢弃并记录在 problems 里 */
+  readonly tier: TierMapping;
+  /** `status.enabled`；未声明时为 undefined（落回包内 config.json 的兜底默认） */
+  readonly statusEnabled: boolean | undefined;
+  readonly problems: readonly string[];
+}
+
+const SECTION_LABEL = `modules.${SUBAGENTS_MODULE_ID}`;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * 读 `modules.subagents` 节。校验直接复用 src/routing.ts 的 parseTierConfig，
+ * 保证菜单里看到的判定与 spawn 时的判定完全一致（同一份严格规则）。
+ */
+export function readSubagentsSection(section: Record<string, unknown>): SubagentsSectionView {
+  const problems: string[] = [];
+
+  const tier: TierMapping = {};
+  const rawModels = section.models;
+  if (rawModels !== undefined) {
+    const parsed = parseTierConfig({ models: rawModels }, SECTION_LABEL);
+    if ("error" in parsed) problems.push(parsed.error);
+    else Object.assign(tier, parsed.config.models);
+  }
+
+  let statusEnabled: boolean | undefined;
+  const status = section.status;
+  if (status !== undefined) {
+    if (!isPlainObject(status)) {
+      problems.push(`${SECTION_LABEL}.status must be an object`);
+    } else if (status.enabled !== undefined) {
+      if (typeof status.enabled === "boolean") statusEnabled = status.enabled;
+      else problems.push(`${SECTION_LABEL}.status.enabled must be a boolean`);
+    }
+  }
+
+  return { tier, statusEnabled, problems };
+}
+
+/**
+ * 本节点路径。菜单写盘与错误提示定位共用它——spawn 时的同一级来源也指向这里。
+ */
+export function subagentsSectionPath(agentDir?: string): string {
+  return `${getToolkitConfigPath(agentDir ?? getAgentDir())} (${SECTION_LABEL})`;
+}
+
+/**
+ * 按 spawn 时的同一规则解析生效的 tier 配置（含第 4 级本节点注入），
+ * 供菜单展示与缺映射报错使用。
+ */
+export function loadEffectiveTierConfig(options?: {
+  readonly cwd?: string;
+  readonly agentDir?: string;
+}): TierConfigLoadResult {
+  return loadTierRouteConfig({
+    cwd: options?.cwd ?? process.cwd(),
+    agentConfigDir: options?.agentDir ?? getAgentConfigDir(),
+    injected: resolveHostTierSources(),
+  });
+}
+
+/**
+ * 某一档缺映射时的报错文案。走 src/routing.ts 的 resolveTierForParams，
+ * 与真正 spawn 时抛出的字符串逐字一致（含"Add models.x to <path>"与
+ * "No pi-subagents config was found (looked at …)"两条原文）。
+ */
+export function tierRouteError(tier: ModelTier, load: () => TierConfigLoadResult): string | undefined {
+  const resolution = resolveTierForParams({ tier }, load);
+  return "error" in resolution ? resolution.error : undefined;
+}
+
+function assertModelValue(tier: ModelTier, model: string, source: string): void {
+  const checked = parseTierConfig({ models: { [tier]: model } }, source);
+  if ("error" in checked) throw new Error(checked.error);
+}
+
+export interface SubagentsWriteOptions {
+  readonly agentDir?: string;
+}
+
+/** 写一档 tier 的模型映射到本节点 */
+export async function saveTierModel(
+  tier: ModelTier,
+  model: string,
+  options: SubagentsWriteOptions = {},
+): Promise<void> {
+  const path = getToolkitConfigPath(options.agentDir ?? getAgentDir());
+  assertModelValue(tier, model, path);
+  await saveToolkitConfig(path, {
+    modules: { [SUBAGENTS_MODULE_ID]: { models: { [tier]: model } } },
+  });
+}
+
+/** 写状态显示开关到本节点 */
+export async function saveStatusEnabled(
+  enabled: boolean,
+  options: SubagentsWriteOptions = {},
+): Promise<void> {
+  const path = getToolkitConfigPath(options.agentDir ?? getAgentDir());
+  await saveToolkitConfig(path, {
+    modules: { [SUBAGENTS_MODULE_ID]: { status: { enabled } } },
+  });
+}

package/modules/subagents/index.ts

@@ -0,0 +1,91 @@
+// 子代理模块：把 pi-subagents 整体装进 pi-toolkit。
+//
+// 迁入原则是搬移优先于重写：`src/` 下是原 pi-subagents 的全部实现（只加了
+// 宿主配置注入点与命令注册开关），`agents/` 是随包代理定义，
+// `config.json.example` 是包内兜底配置。目录形状保持 `src/` 相对两层到包根，
+// 因此 `SUBAGENTS_DIR` / `PACKAGE_ROOT`、`-e` 装载路径、trustedRoots
+// containment、agents 发现路径全部沿用原规则，不需要改算法。
+//
+// 这里只做装配：
+//   - 6 个模型侧工具（subagent / subagent_message / subagents_list /
+//     subagent_inspect / subagent_stop / team_dispatch）+ 4 个消息渲染器 +
+//     状态 widget + 2 个事件钩子（session_start / session_shutdown）按
+//     ModuleDefinition 注册；enabled=false 时装配器根本不调用 register
+//   - 旧 `/subagent` 命令不再注册（合并决策 5）
+//   - tier 模型路由与状态显示开关读写 pi-toolkit.json 的 `modules.subagents` 节
+//   - 服务句柄 `subagents.running`：供其它模块查询子代理运行状态
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { getToolkitConfigPath } from "../../config.ts";
+import { enabledField, type ModuleContext, type ModuleDefinition } from "../../module.ts";
+import { SUBAGENTS_MODULE_ID } from "./config.ts";
+import { buildSubagentsMenuItems, type SubagentsMenuRuntime } from "./menu.ts";
+import subagentsExtension, {
+  listRunningSubagents,
+  runtimeRegistryPathForSession,
+  type SubagentsHostSection,
+} from "./src/index.ts";
+import { readRuntimeRecords, type RuntimeRecord } from "./src/runtime-registry.ts";
+
+export { SUBAGENTS_MODULE_ID } from "./config.ts";
+
+/** 服务句柄名（注册表要求全小写） */
+export const SUBAGENTS_SERVICE_NAME = "subagents.running";
+
+export interface SubagentsService {
+  readonly id: "subagents";
+  /** 进程内运行中的子代理数量（与状态 widget 同源，实时） */
+  runningCount(): number;
+  /** 进程内运行中的子代理名（便于其它模块做哨兵判断） */
+  runningNames(): readonly string[];
+  /** 会话作用域的持久化运行态登记：沿用 runtime-registry 的既有数据 */
+  runtimeRecords(sessionDir: string, sessionId: string): RuntimeRecord[];
+}
+
+function registerSubagents(context: ModuleContext, runtime: SubagentsMenuRuntime): void {
+  runtime.reload = () => context.reloadConfig();
+
+  // 宿主注入：本节点就是 pi-toolkit.json 的 `modules.subagents` 节。
+  // getConfig() 返回状态中枢解析后的本模块配置（schema 默认值 + 磁盘取值），
+  // 非 schema 键原样透传，因此 models / status 直接可用；写盘后由 reloadConfig 刷新。
+  subagentsExtension(context.pi, {
+    registerCommand: false,
+    readHostSection: (): SubagentsHostSection => ({
+      source: `${getToolkitConfigPath(getAgentDir())} (modules.${SUBAGENTS_MODULE_ID})`,
+      section: context.getConfig(),
+    }),
+  });
+
+  context.services.register(SUBAGENTS_SERVICE_NAME, {
+    id: "subagents",
+    runningCount: () => listRunningSubagents().length,
+    runningNames: () => listRunningSubagents().map((running) => running.name),
+    runtimeRecords: (sessionDir, sessionId) =>
+      readRuntimeRecords(runtimeRegistryPathForSession(sessionDir, sessionId)),
+  } satisfies SubagentsService);
+}
+
+export function createSubagentsModule(): ModuleDefinition {
+  // 菜单写盘后要让状态中枢重新读盘，否则 getConfig() 还是旧副本
+  const runtime: SubagentsMenuRuntime = { reload: async () => {} };
+
+  return {
+    id: SUBAGENTS_MODULE_ID,
+    labelKey: "module.subagents.label",
+    descriptionKey: "module.subagents.description",
+    group: "subagents",
+    // schema 只放总开关；tier 路由与 status 开关是结构化配置（非 schema 键），
+    // 由本模块的菜单与配置层读写。
+    configSchema: {
+      enabled: enabledField("module.subagents.enabled.label", "module.subagents.enabled.description"),
+    },
+    register(context): void {
+      registerSubagents(context, runtime);
+    },
+    menuItems(context): ReturnType<typeof buildSubagentsMenuItems> {
+      return buildSubagentsMenuItems(context, runtime);
+    },
+  };
+}
+
+export const subagentsModule: ModuleDefinition = createSubagentsModule();