pi-herdr-subagents-lite 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 setwhite
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,198 @@
-# Temporary Holding Version
+# pi-herdr-subagents-lite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [简体中文](README.zh-CN.md)
+
+A pi extension that runs subagents as separate pi processes in herdr panes. One tool, two actions: `run` starts a subagent, `send` continues it, results come back asynchronously.
+
+Experimental; compatibility across versions is not promised. Exact behavior lives in the [v1 contract](docs/specs/0001-v1-contract.md). Project docs are in Chinese.
+
+## 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.
+- **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.
+
+## Requirements
+
+herdr `0.9.5`, pi `1.4.0`, Node `>= 22.19`. The parent must run inside a herdr pane, otherwise calls fail with `not_in_herdr`.
+
+## Install
+
+Pick one source, then restart pi.
+
+```bash
+pi install npm:pi-herdr-subagents-lite                     # npm
+pi install git:github.com/setwhite/pi-herdr-subagents-lite # git
+pi install /path/to/pi-herdr-subagents-lite                # local checkout
+pi -e /path/to/pi-herdr-subagents-lite/src/index.ts        # this process only
+```
+
+Do not pass `-l`: it writes project settings only, so children started in another workspace never load the package and both the inbox pump and the bridge stop working. `pi -e` is single-process too.
+
+Upgrade with `pi update --extensions`, remove with `pi remove <source>`. After a restart the tool list shows `subagent` (or your `toolName`).
+
+## 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.
+3. Ask the model to call the tool:
+
+```json
+{"action":"run","profile":"explore","task":"Read README.md and answer with its first heading."}
+```
+
+It returns `{"state":"running",...}`, runs in its own tab, and a `[subagent explore-1] done` message arrives later. Do not wait for it in the same turn. Continue that child with:
+
+```json
+{"action":"send","name":"explore-1","message":"Also check the Windows branch."}
+```
+
+## 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.
+
+```markdown
+---
+# Listed as "file (name)"; run takes the file name
+name: Explore
+description: "Read-only research: read code, answer questions, change nothing"
+
+# Omit to inherit from the parent
+# model: provider/model
+thinking: low
+
+# Plain names = strict allowlist; +name / -name adjusts the default set, never mix both
+# Omitted = pi defaults minus this tool (nesting off); "" = empty allowlist
+tools: read, bash
+
+# Omitted = pi discovery; "" = no skills; a list = only those
+skills: ""
+
+# append (default) / replace: body is appended to or replaces the system prompt
+# task: body is the task text, no identity file
+system-prompt: append
+
+# Shut down and close the tab when settled; waits while a prompt is open or the inbox has messages
+auto-exit: true
+
+# true = hidden from the guidelines; an explicit run still works
+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.
+
+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:
+
+```bash
+cd ~/.pi/agent/pi-herdr-subagents-lite/profiles && cp examples/domain.md domain.md
+```
+
+## Configuration
+
+One global file: `<agent-dir>/pi-herdr-subagents-lite/config.json`. `<agent-dir>` defaults to `~/.pi/agent` and follows `PI_CODING_AGENT_DIR`. Project config is not read.
+
+### Minimal config
+
+A missing file means all defaults. To change one value, write only that value:
+
+```json
+{
+  "maxConcurrent": 4
+}
+```
+
+### Full config
+
+Every key with its default. Strict JSON: an unknown key, a wrong type or a bad enum makes the extension fail to load and pi exits naming the field. The `//` lines are comments; delete them before use.
+
+```jsonc
+{
+  // Gates tool registration only; the bridge has its own switch
+  "enabled": true,
+
+  // Name the model sees; ^[a-z][a-z0-9_]{0,31}$
+  "toolName": "subagent",
+
+  // Resolved from PATH; set an absolute path to pin a version
+  "herdrBin": "herdr",
+
+  // Live children per parent session; auto-exit false keeps its slot after settling
+  "maxConcurrent": 16,
+
+  // Per result (1024-1048576); beyond it the full text goes to an artifact and the message keeps a truncated head plus the path
+  "maxResultChars": 16384,
+
+  // Ms (0-10000); results inside the window merge into one message, 0 = deliver each immediately
+  "aggregateWindowMs": 500,
+
+  // Parent shutdown reasons that close its child tabs: new / resume / fork / quit / reload; empty = never
+  "closeChildrenOn": [],
+
+  // Child inbox polling interval in ms (50-5000)
+  "inboxPollMs": 250,
+
+  // Parent agent list polling in ms (100-60000); larger saves processes, smaller spots finished children sooner
+  "pollIntervalMs": 1000,
+
+  // Override tool text. Omitted keys keep the built-in text; the values are placeholders, drop the whole block if unused
+  "prompts": {
+    "description": "One line about what this tool does",
+    "snippet": "One line shown in Available tools",
+    // Keep a line containing {{profiles}} to keep the profile list
+    "guidelines": ["Do not wait for a result in this turn.", "Available profiles:\n{{profiles}}"]
+  },
+
+  // Turns pi prompt events into herdr:blocked, for native notifications
+  "bridge": {
+    "enabled": true,
+    // Which prompt kinds count as blocked
+    "blockedOn": ["custom", "select", "confirm", "input", "editor"]
+  }
+}
+```
+
+Out-of-range numbers are clamped to the boundary, not rejected. The config is read once, so restart pi after editing.
+
+## Reference projects
+
+The design is based on these projects. Thank you.
+
+| Project | Borrowed |
+|---|---|
+| [earendil-works/pi](https://github.com/earendil-works/pi) | Extension API, package layout, official examples |
+| [fyang93/pi-herdr-subagents](https://github.com/fyang93/pi-herdr-subagents) | Profile field shapes; integration tests on an isolated herdr session |
+| [modem-dev/pi-herdr-subagents](https://github.com/modem-dev/pi-herdr-subagents) | herdr launch and lifecycle; derived end states |
+| [purboo/pi-durable-subagents](https://github.com/purboo/pi-durable-subagents) | Async delivery, idempotency, report-once results |
+
+## Docs
+
+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
+
+## Development
+
+```bash
+pnpm install        # dependencies
+pnpm check          # lint + import boundaries + types + unit tests
+pnpm test           # unit tests (vitest)
+pnpm lint           # biome
+pnpm typecheck      # tsc --noEmit
+pnpm check:imports  # dependency direction, per docs/ARCHITECTURE.md
+pnpm test:e2e       # real herdr plus real pi children, not part of pnpm check
+```
+
+Run `git config core.hooksPath .githooks` once to run `pnpm check` on every commit.
+
+E2E starts an isolated herdr session and agent directory, and skips the suite with a reason when herdr, pi or `auth.json` is missing. `PI_E2E_MODEL` picks another model; `PI_E2E_KEEP=1` keeps the temp directories.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,196 @@
+# pi-herdr-subagents-lite
+
+[English](README.md) | 简体中文
+
+pi 扩展：让子代理作为独立 pi 进程跑在 herdr pane 里。一个工具，两个 action：`run` 起子代理，`send` 续聊，结果异步回投。
+
+实验阶段，不保证跨版本兼容。行为以 [v1 契约](docs/specs/0001-v1-contract.md) 为准。
+
+## 功能
+
+- **独立进程，可人工接管**：每个子代理是 herdr pane 里独立的 pi 进程。cwd 与父相同则同 workspace 新开 tab，否则新建 workspace。随时切进去接管。
+- **两层 profile**：Markdown + frontmatter，全局 `<agent-dir>/pi-herdr-subagents-lite/profiles/`，项目层 `.pi/pi-herdr-subagents-lite/profiles/`，同名时项目层覆盖。
+- **异步、可合并的结果**：`run` 立即返回。每个子代理收工时投一条 `subagent_result`；落在 `aggregateWindowMs` 内的结果合并成一条。超长结果落 artifact 文件。
+- **反问留在人这边**：子代理弹出对话框时只发出 `herdr:blocked` 事件，父侧什么也收不到。人在子 pane 里回答，不经模型转达。
+- **默认不嵌套，也不是沙箱**：子代理的工具集默认去掉本工具，profile 里点名才授予。工具由 profile 决定，扩展不限制写操作。
+
+## 要求
+
+herdr `0.9.5`、pi `1.4.0`、Node `>= 22.19`。父会话必须在 herdr pane 里，否则调用返回 `not_in_herdr`。
+
+## 安装
+
+选一种来源，装完重启 pi。
+
+```bash
+pi install npm:pi-herdr-subagents-lite                     # npm
+pi install git:github.com/setwhite/pi-herdr-subagents-lite # git
+pi install /path/to/pi-herdr-subagents-lite                # 本地源码
+pi -e /path/to/pi-herdr-subagents-lite/src/index.ts        # 只对当前进程生效
+```
+
+不要加 `-l`：它只写项目设置，在别的 workspace 里起的子代理就加载不到，inbox 泵和 bridge 都会失效。`pi -e` 同样是单进程。
+
+升级用 `pi update --extensions`，卸载用 `pi remove <source>`。重启后工具列表里出现 `subagent`（或你配的 `toolName`）。
+
+## 快速开始
+
+1. 在 herdr pane 里启动 `pi`。
+2. 写一个 profile（下一节）；文件名去掉 `.md` 就是 `run` 的寻址名。
+3. 让模型调用工具：
+
+```json
+{"action":"run","profile":"explore","task":"读 README.md，回答它的第一个标题。"}
+```
+
+它返回 `{"state":"running",...}`，子代理在自己的 tab 里跑，稍后收到 `[subagent explore-1] done` 消息。不要在同一轮里等结果。续聊那个子代理：
+
+```json
+{"action":"send","name":"explore-1","message":"也看一下 Windows 那条分支。"}
+```
+
+## Profile
+
+全局 profile 在 `<agent-dir>/pi-herdr-subagents-lite/profiles/*.md`，项目 profile 在 `.pi/pi-herdr-subagents-lite/profiles/*.md`（项目受信任后才读）；同名时项目覆盖全局。
+
+```markdown
+---
+# 列表写作「文件名 (显示名)」；run 取文件名
+name: Explore
+description: 只读调研：读代码、回答问题，不改动任何文件
+
+# 省略即继承父会话
+# model: provider/model
+thinking: low
+
+# 纯名字 = 严格白名单；+名字 / -名字 在默认集上增删，两者不能混用
+# 省略 = pi 默认集去掉本工具（不嵌套）；"" = 空白名单
+tools: read, bash
+
+# 省略 = 由 pi 发现；"" = 不加载；列表 = 只加载列出的
+skills: ""
+
+# append（默认）/ replace：正文追加到或替换系统提示
+# task：正文就是任务文本，不写身份文件
+system-prompt: append
+
+# 收工后自行退出并关掉 tab；有打开的对话框或 inbox 待投递时会等
+auto-exit: true
+
+# true = 从工具说明里隐藏；显式 run 仍然可用
+disable-model-invocation: false
+---
+
+你是一名只读探索者，回答时给出文件路径与行号。
+```
+
+字段默认值与错误码见 [契约 §2](docs/specs/0001-v1-contract.md#2-profile)。解析失败的文件不进列表；对它 `run` 返回 `profile_invalid`，带文件、字段与原因。
+
+扩展自带一个示例 profile。加载只读 `profiles/*.md`，示例也只在缺失时写入，所以复制一层上去即可：
+
+```bash
+cd ~/.pi/agent/pi-herdr-subagents-lite/profiles && cp examples/domain.md domain.md
+```
+
+## 配置
+
+只有一个全局文件：`<agent-dir>/pi-herdr-subagents-lite/config.json`。`<agent-dir>` 默认 `~/.pi/agent`，跟随 `PI_CODING_AGENT_DIR`。项目级配置不读。
+
+### 最小配置
+
+文件不存在就全用默认值。只改一项，就只写这一项：
+
+```json
+{
+  "maxConcurrent": 4
+}
+```
+
+### 完整配置
+
+逐项列出，值是默认值。必须是严格 JSON：未知键、类型不对、枚举非法都会让扩展加载失败，pi 报出字段名退出。`//` 行是注释，用之前删掉。
+
+```jsonc
+{
+  // 只管工具注册；bridge 有自己的开关
+  "enabled": true,
+
+  // 模型看到的工具名；^[a-z][a-z0-9_]{0,31}$
+  "toolName": "subagent",
+
+  // 从 PATH 解析；写绝对路径可锁定版本
+  "herdrBin": "herdr",
+
+  // 每个父会话并存的子代理数；auto-exit 为 false 的子代理收工后仍占槽
+  "maxConcurrent": 16,
+
+  // 单条结果上限（1024-1048576）；超了全文落 artifact，消息里留截断的头和路径
+  "maxResultChars": 16384,
+
+  // 合并窗口，毫秒（0-10000）；窗口内的结果并成一条，0 = 逐条立即投递
+  "aggregateWindowMs": 500,
+
+  // 父会话以这些原因退出时关掉子 tab：new / resume / fork / quit / reload；空 = 从不关
+  "closeChildrenOn": [],
+
+  // 子侧 inbox 轮询间隔，毫秒（50-5000）
+  "inboxPollMs": 250,
+
+  // 父侧 agent list 轮询间隔，毫秒（100-60000）；调大省进程，调小更早发现收工
+  "pollIntervalMs": 1000,
+
+  // 覆盖工具文案。省略的键用内置文案；下面的值是占位符，不用就整段删掉
+  "prompts": {
+    "description": "一句话说明这个工具做什么",
+    "snippet": "Available tools 里的一句话",
+    // 保留含 {{profiles}} 的行才会保留 profile 列表
+    "guidelines": ["不要在本轮等待结果。", "可用 profile：\n{{profiles}}"]
+  },
+
+  // 把 pi 的对话框事件转成 herdr:blocked，供原生通知使用
+  "bridge": {
+    "enabled": true,
+    // 哪些对话框算 blocked
+    "blockedOn": ["custom", "select", "confirm", "input", "editor"]
+  }
+}
+```
+
+超范围的数字会被夹到边界，不报错。配置只读一次，改完重启 pi。
+
+## 参考项目
+
+设计参考了这些项目，感谢作者。
+
+| 项目 | 借鉴内容 |
+|---|---|
+| [earendil-works/pi](https://github.com/earendil-works/pi) | 扩展 API、包布局、官方示例 |
+| [fyang93/pi-herdr-subagents](https://github.com/fyang93/pi-herdr-subagents) | profile 字段形状；隔离 herdr session 的集成测试 |
+| [modem-dev/pi-herdr-subagents](https://github.com/modem-dev/pi-herdr-subagents) | herdr 启动与生命周期；终态归类 |
+| [purboo/pi-durable-subagents](https://github.com/purboo/pi-durable-subagents) | 异步投递、幂等、只上报一次 |
+
+## 文档
+
+- [ARCHITECTURE](docs/ARCHITECTURE.md) — 模块边界与 seam，改结构前看
+- [GLOSSARY](docs/GLOSSARY.md) — 术语唯一来源，命名前看
+- [模块](docs/modules/) — 各模块的用法与取舍
+
+## 开发
+
+```bash
+pnpm install        # 装依赖
+pnpm check          # lint + 导入边界 + 类型 + 单测
+pnpm test           # 单测（vitest）
+pnpm lint           # biome
+pnpm typecheck      # tsc --noEmit
+pnpm check:imports  # 依赖方向，按 docs/ARCHITECTURE.md 校验
+pnpm test:e2e       # 真 herdr + 真 pi 子进程，不在 pnpm check 里
+```
+
+跑一次 `git config core.hooksPath .githooks`，之后每次提交都会跑 `pnpm check`。
+
+E2E 自己起隔离的 herdr session 与 agent 目录，缺 herdr、pi 或 `auth.json` 时整组跳过并给出原因。`PI_E2E_MODEL` 换模型；`PI_E2E_KEEP=1` 保留临时目录。
+
+## 许可
+
+MIT，见 [LICENSE](LICENSE)。

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "pi-herdr-subagents-lite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Run pi subagents in herdr panes.",
+  "type": "module",
+  "license": "MIT",
+  "author": "setwhite",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/setwhite/pi-herdr-subagents-lite.git"
+  },
+  "keywords": ["pi-package", "pi-extension", "herdr", "subagent"],
+  "files": ["src"],
+  "packageManager": "pnpm@12.3.4",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "lint": "biome check --error-on-warnings .",
+    "check:imports": "node scripts/check-imports.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "check": "pnpm lint && pnpm check:imports && pnpm typecheck && pnpm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.2",
+    "@earendil-works/pi-coding-agent": "^1.4.0",
+    "@types/node": "^26.6.5",
+    "typebox": "^1.3.27",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  }
+}

package/src/bridge/index.ts

@@ -0,0 +1,24 @@
+import type { BlockedKind, Config } from "../config/index.ts";
+
+interface BridgePi {
+  on(event: "ui_prompt_start" | "ui_prompt_end", handler: (event: { kind: BlockedKind; title?: string }) => void): void;
+  events: { emit(channel: "herdr:blocked", data: { active: boolean; label?: string }): void };
+}
+
+export function createBridge(pi: BridgePi, config: Config["bridge"]): void {
+  if (!config.enabled) {
+    return;
+  }
+  pi.on("ui_prompt_start", (event) => {
+    if (!config.blockedOn.includes(event.kind)) {
+      return;
+    }
+    pi.events.emit("herdr:blocked", { active: true, label: event.title ?? event.kind });
+  });
+  pi.on("ui_prompt_end", (event) => {
+    if (!config.blockedOn.includes(event.kind)) {
+      return;
+    }
+    pi.events.emit("herdr:blocked", { active: false });
+  });
+}

package/src/config/index.ts

@@ -0,0 +1,122 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  BLOCKED_KINDS,
+  BRIDGE_KEYS,
+  boolean,
+  CONFIG_KEYS,
+  enumList,
+  integer,
+  isRaw,
+  nonEmptyString,
+  object,
+  optionalString,
+  PROMPT_KEYS,
+  type Raw,
+  type Scope,
+  SHUTDOWN_REASONS,
+  stringArray,
+  toolName,
+  unknownKeys,
+} from "./schema.ts";
+
+export { isRaw, type Raw } from "./schema.ts";
+
+export type BlockedKind = (typeof BLOCKED_KINDS)[number];
+export type ShutdownReason = (typeof SHUTDOWN_REASONS)[number];
+
+interface PromptOverrides {
+  description?: string;
+  snippet?: string;
+  guidelines?: string[];
+}
+
+export interface Config {
+  enabled: boolean;
+  toolName: string;
+  herdrBin: string;
+  maxConcurrent: number;
+  maxResultChars: number;
+  aggregateWindowMs: number;
+  closeChildrenOn: ShutdownReason[];
+  inboxPollMs: number;
+  pollIntervalMs: number;
+  prompts: PromptOverrides;
+  bridge: { enabled: boolean; blockedOn: BlockedKind[] };
+}
+
+function promptOverrides(scope: Scope): PromptOverrides {
+  const prompts = object(scope, "prompts", PROMPT_KEYS);
+  const overrides: PromptOverrides = {};
+  for (const key of ["description", "snippet"] as const) {
+    const line = optionalString(prompts, key);
+    if (line !== undefined) {
+      overrides[key] = line;
+    }
+  }
+  const guidelines = stringArray(prompts, "guidelines");
+  if (guidelines !== undefined) {
+    overrides.guidelines = guidelines;
+  }
+  return overrides;
+}
+
+function parse(raw: Raw, file: string): Config {
+  const problems: string[] = [];
+  const top: Scope = { raw, prefix: "", problems };
+  unknownKeys(top, CONFIG_KEYS);
+  const bridge = object(top, "bridge", BRIDGE_KEYS);
+
+  const config: Config = {
+    enabled: boolean(top, "enabled", true),
+    toolName: toolName(top),
+    herdrBin: nonEmptyString(top, "herdrBin", "herdr"),
+    maxConcurrent: integer(top, "maxConcurrent", 16, 1, Number.POSITIVE_INFINITY),
+    maxResultChars: integer(top, "maxResultChars", 16384, 1024, 1048576),
+    aggregateWindowMs: integer(top, "aggregateWindowMs", 500, 0, 10000),
+    closeChildrenOn: enumList(top, "closeChildrenOn", SHUTDOWN_REASONS, []),
+    inboxPollMs: integer(top, "inboxPollMs", 250, 50, 5000),
+    pollIntervalMs: integer(top, "pollIntervalMs", 1000, 100, 60000),
+    prompts: promptOverrides(top),
+    bridge: {
+      enabled: boolean(bridge, "enabled", true),
+      blockedOn: enumList(bridge, "blockedOn", BLOCKED_KINDS, BLOCKED_KINDS),
+    },
+  };
+
+  if (problems.length > 0) {
+    throw new Error(`invalid config ${file}: ${problems.join("; ")}`);
+  }
+  return config;
+}
+
+function readRaw(file: string): Raw {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return {};
+    }
+    throw error;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`invalid config ${file}: not valid JSON`);
+  }
+  if (!isRaw(parsed)) {
+    throw new Error(`invalid config ${file}: expected a JSON object`);
+  }
+  return parsed;
+}
+
+export function dataDir(agentDir: string): string {
+  return join(agentDir, "pi-herdr-subagents-lite");
+}
+
+export function loadConfig(agentDir: string): Config {
+  const file = join(dataDir(agentDir), "config.json");
+  return parse(readRaw(file), file);
+}