@oldflag2333333/pi-subagent 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Facets contributors
+
+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,172 @@
-# Temporary Holding Version
+# Pi Subagent
 
-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)
+
+Give Pi reusable specialists for code review, research, and other focused tasks. Each specialist runs in its own Herdr tab and reports back to your main conversation, without inheriting its chat history.
+
+A **profile** defines a specialist's instructions, tools, and optional skills or model. You can invoke it yourself or let your main Pi delegate work to it.
+
+## Install
+
+You need **Node.js 22.19+**, **[Pi](https://pi.dev) 1.0.4+**, and **Herdr**. To launch specialists, run Pi inside a Herdr workspace with the `herdr` command available.
+
+```bash
+pi install npm:@oldflag2333333/pi-subagent
+```
+
+Restart Pi or run `/reload`. Pi Subagent uses your existing Pi provider credentials; make sure Pi can already run a normal conversation.
+
+To update later:
+
+```bash
+pi update npm:@oldflag2333333/pi-subagent
+```
+
+Restart Pi or run `/reload` after updating.
+
+## Try it: a code reviewer
+
+Pi Subagent ships without built-in profiles. Create your first one:
+
+```bash
+mkdir -p ~/.pi/agent/subagent/profiles/reviewer
+```
+
+Save this as `~/.pi/agent/subagent/profiles/reviewer/config.json`:
+
+```json
+{
+  "version": 1,
+  "name": "reviewer",
+  "description": "Review code for bugs and missing tests without modifying files.",
+  "tools": ["read", "grep", "find", "ls"]
+}
+```
+
+Save this beside it as `instructions.md`:
+
+```markdown
+Review the requested code for bugs, regressions, and missing tests.
+Do not modify files. Report actionable findings with file paths and
+line numbers. If nothing stands out, say so and note any testing gaps.
+```
+
+In Pi, run `/reload`, then:
+
+```text
+/sub:reviewer Review the authentication code in src/auth.
+```
+
+Replace `src/auth` with a path in your project. The reviewer opens in a separate Herdr tab and sends its findings back to your main conversation. You can keep working while it runs.
+
+Or ask your main Pi to delegate:
+
+```text
+Ask the reviewer profile to review src/auth for bugs and missing tests.
+```
+
+## Everyday use
+
+| What you want | How to do it |
+| --- | --- |
+| See available profiles or configuration errors | `/profiles` |
+| Start a specialist or send it another task | `/sub:reviewer <task>` |
+| Let Pi choose a specialist | Ask Pi to delegate the task to an appropriate profile |
+| Check progress | Ask Pi to list its Subs, or open the specialist's Herdr tab |
+| Stop its current task without closing it | Ask Pi to interrupt the Sub |
+| Finish with a specialist | Ask Pi to close the Sub, or close its Herdr tab |
+| Remove communication files left by deleted Main sessions | `/clean-sub` |
+
+Within the same Main session, repeated `/sub:reviewer` commands reuse that profile's open Sub. If it is busy, your next task is queued. Finishing a task does not automatically close the tab.
+
+The **Sub-agents** list shows only assistants created by the current Main: all **Open** Subs (including idle or unknown status) and **Resumable** persistent sessions confirmed closed with saved files still available. Other Main sessions and forks do not inherit them or gain access to resume them. Reloading or resuming the same Main preserves ownership.
+
+To use a profile in your current Pi instead of opening a Sub, start Pi with:
+
+```bash
+pi --profile reviewer
+```
+
+Starting Pi without `--profile` leaves your existing tools, model, and skills unchanged.
+
+## Customize a profile
+
+### Where profiles live
+
+- **Personal:** `~/.pi/agent/subagent/profiles/<name>/`
+- **Project:** `.pi/subagent/profiles/<name>/` in your project or an ancestor directory; loaded only when the project is trusted.
+
+Each directory needs a `config.json`, with a `name` matching the directory name. A nearer project profile replaces a same-named ancestor or personal profile; settings are not merged. Legacy `<name>.json` profiles are also supported.
+
+### Instructions
+
+Write the role in `instructions.md` beside `config.json`. It takes precedence over an inline `"instructions": "..."` field; if the file is absent, the inline field is used instead. Instructions add to Pi's normal project context, rather than replacing it.
+
+Instruction files must be non-empty and no longer than 65,536 characters. An invalid or unreadable file is reported as an error, not silently ignored.
+
+Run `/reload` after editing profiles. Already-open Subs keep their launch configuration; close and reopen them to use changes.
+
+### Optional settings
+
+Add these fields to `config.json` as needed:
+
+| Field | Use it to… |
+| --- | --- |
+| `"invocation": "manual"` | Allow only user commands such as `/sub:reviewer` to start this specialist. Default: `"both"`, allowing Pi delegation too. |
+| `"sessionPersistence": "persistent"` | Save the Sub's conversation so it can be resumed after closing. Default: `"ephemeral"`, which keeps it only in memory. |
+| `"model": "provider/model-id"` | Choose a model available in your Pi configuration. |
+| `"thinkingLevel": "high"` | Request a thinking level supported by the selected model. |
+| `"skills": ["skill-name", "./path/to/SKILL.md"]` | Include installed skills or paths relative to the profile. |
+
+For a persistent specialist started with `/sub:reviewer`, invoking the command again from the same saved Main session resumes it after closure. A different Main session gets its own specialist. Manual-only profiles are not available for Pi to delegate on its own.
+
+### Profile-specific skills
+
+Put skills inside the profile directory to load them only when that profile is selected. No `skills` field is needed:
+
+```text
+reviewer/
+├── config.json
+├── instructions.md
+└── skills/
+    └── code-review/
+        └── SKILL.md
+```
+
+### Delegation rules for your main Pi
+
+Use `~/.pi/agent/subagent/MAIN.md` or a trusted project's `.pi/subagent/MAIN.md` for rules such as:
+
+```markdown
+Ask the reviewer profile to review code changes before declaring a task complete.
+```
+
+These instructions apply only to your main Pi, not to its Subs. Keep shared project rules in `AGENTS.md`.
+
+## Clean up deleted sessions
+
+Run `/clean-sub` to immediately delete runtime communication directories whose Main ID is no longer found among saved Pi sessions. It checks the default session store and the current session directory, always preserves the current Main, and creates no index. If session files cannot be read or their headers are invalid, cleanup stops rather than treating them as deleted.
+
+Persistent Sub `.jsonl` files are **not deleted**; remove them manually through Pi's session picker. Profiles and global settings are untouched. The command does not close Herdr tabs. If you moved Main files or use other custom session directories, make them available in the scanned locations before cleaning.
+
+## Things to know
+
+- **Herdr is required for Subs.** There is no headless fallback. Up to four Subs can be open at once, and Subs cannot delegate further.
+- **Profiles are not a sandbox.** Subs run as your OS user. A read-only role is not a filesystem permission boundary.
+- **MCP follows Pi's normal configuration.** Profiles select non-MCP tools; they do not isolate or filter MCP servers. Custom non-MCP tools must come from extensions already loaded in Main.
+- **Subs have separate conversations.** They receive their task, profile, and normal project context—not Main's chat history. Include the details they need in the task.
+- **Reloading Main does not close Subs.** Close tabs you no longer need. Hard crashes may require manual cleanup.
+
+If a profile is missing or fails to start, run `/profiles` first. Check its directory/name match, project trust, and any referenced tools or skills. If Herdr is unavailable, confirm Pi is running inside a Herdr workspace.
+
+To hide or show Pi Subagent Subs in Herdr's Agents panel, see the optional [Herdr companion plugin](herdr-plugin/README.md).
+
+## Development
+
+```bash
+npm install
+npm run check
+pi -e ./src/index.ts
+```
+
+Maintainers: see [the release guide](docs/releasing.md) for CI and automatic npm publishing.

package/README.zh-CN.md

@@ -0,0 +1,172 @@
+# Pi Subagent
+
+[English](README.md) | 简体中文
+
+给 Pi 配置可复用的专用助手，用于代码审查、资料调研等任务。每个助手都在独立的 Herdr 标签页中工作，将结果发回主对话，不继承主对话的聊天记录。
+
+一份 **profile（角色配置）** 定义助手的指令、工具，以及可选的技能和模型。你可以手动调用，也可以让主 Pi 自行委派任务。
+
+## 安装
+
+需要 **Node.js 22.19+**、**[Pi](https://pi.dev) 1.0.4+** 和 **Herdr**。启动助手时，Pi 必须运行在 Herdr 工作区中，并且能调用 `herdr` 命令。
+
+```bash
+pi install npm:@oldflag2333333/pi-subagent
+```
+
+安装后重启 Pi，或执行 `/reload`。Pi Subagent 使用 Pi 已有的模型服务凭据，请先确认 Pi 能正常对话。
+
+后续更新：
+
+```bash
+pi update npm:@oldflag2333333/pi-subagent
+```
+
+更新后同样需要重启 Pi 或执行 `/reload`。
+
+## 快速上手：代码审查助手
+
+Pi Subagent 不附带内置角色。先创建一个：
+
+```bash
+mkdir -p ~/.pi/agent/subagent/profiles/reviewer
+```
+
+将以下内容保存为 `~/.pi/agent/subagent/profiles/reviewer/config.json`：
+
+```json
+{
+  "version": 1,
+  "name": "reviewer",
+  "description": "检查代码中的缺陷和测试遗漏，不修改文件。",
+  "tools": ["read", "grep", "find", "ls"]
+}
+```
+
+在同一目录下创建 `instructions.md`：
+
+```markdown
+检查指定代码中的缺陷、回归风险和测试遗漏。
+不要修改文件。报告具体、可操作的问题，并附上文件路径和行号。
+如果没有发现明显问题，请明确说明，并指出尚未验证的部分。
+```
+
+在 Pi 中执行 `/reload`，然后输入：
+
+```text
+/sub:reviewer 检查 src/auth 中的认证代码。
+```
+
+将 `src/auth` 替换为你项目中的路径。审查助手会在独立的 Herdr 标签页中启动，并将结果发回主对话。等待期间，你可以继续处理其他工作。
+
+也可以直接让主 Pi 委派：
+
+```text
+让 reviewer 检查 src/auth 中的缺陷和测试遗漏。
+```
+
+## 日常使用
+
+| 你想做什么 | 操作方式 |
+| --- | --- |
+| 查看可用角色或配置错误 | `/profiles` |
+| 启动助手，或给它追加任务 | `/sub:reviewer <任务>` |
+| 让 Pi 选择助手 | 告诉 Pi 将任务委派给合适的角色 |
+| 查看进度 | 让 Pi 列出子助手，或打开助手的 Herdr 标签页 |
+| 停止当前任务，但保留助手会话 | 让 Pi 中断该子助手 |
+| 结束使用 | 让 Pi 关闭子助手，或手动关闭其 Herdr 标签页 |
+| 清理已删除 Main 遗留的通信文件 | `/clean-sub` |
+
+在同一个主会话（Main）中，多次调用 `/sub:reviewer` 会复用该角色已打开的子助手（Sub）。如果它正在工作，新任务会排队。任务完成后，标签页不会自动关闭。
+
+**Sub-agents（子助手）** 列表只显示当前 Main 创建的助手：**Open** 包含所有已打开的子助手，包括空闲或状态未知的；**Resumable** 包含已确认关闭、且保存文件仍存在的持久化会话。其他 Main 或分叉会话不会继承这些助手，也不能恢复它们。重载或恢复同一个 Main 则会保留关联。
+
+如果想将角色应用到当前 Pi，而不是打开子助手，可以这样启动：
+
+```bash
+pi --profile reviewer
+```
+
+不传入 `--profile` 时，Pi 原有的工具、模型和技能配置保持不变。
+
+## 自定义角色
+
+### 配置放在哪里
+
+- **个人配置：** `~/.pi/agent/subagent/profiles/<name>/`
+- **项目配置：** 项目或其上级目录中的 `.pi/subagent/profiles/<name>/`，仅在项目信任后加载。
+
+每个目录都需要一份 `config.json`，其中的 `name` 必须与目录名一致。距离当前工作目录更近的项目配置会替换上级目录或个人目录中的同名角色，不会合并字段。旧式的 `<name>.json` 单文件配置仍然受支持。
+
+### 角色指令
+
+将角色说明写在 `config.json` 旁边的 `instructions.md` 中。它优先于 JSON 内的 `"instructions": "..."` 字段；文件不存在时才使用 JSON 字段。角色指令会补充 Pi 原有的项目上下文，而不是替换它。
+
+指令文件不能为空，且不能超过 65,536 个字符。文件无效或无法读取时会报错，不会静默忽略。
+
+修改角色后执行 `/reload`。已经打开的子助手保留启动时的配置，需要关闭并重新打开才能使用新配置。
+
+### 可选设置
+
+按需在 `config.json` 中添加：
+
+| 字段 | 作用 |
+| --- | --- |
+| `"invocation": "manual"` | 只允许用户通过 `/sub:reviewer` 等命令启动。默认值为 `"both"`，也允许 Pi 自行委派。 |
+| `"sessionPersistence": "persistent"` | 保存子助手对话，关闭后可以恢复。默认值为 `"ephemeral"`，仅保存在内存中。 |
+| `"model": "provider/model-id"` | 指定 Pi 配置中可用的模型。 |
+| `"thinkingLevel": "high"` | 请求所选模型支持的思考级别。 |
+| `"skills": ["skill-name", "./path/to/SKILL.md"]` | 加载已安装的技能，或使用相对于角色配置的路径。 |
+
+通过 `/sub:reviewer` 启动的持久化助手，在关闭后，可以从同一个已保存的主会话中再次执行该命令来恢复。不同的主会话各自拥有独立的助手。设置为手动调用的角色不能由 Pi 自行委派。
+
+### 角色专属技能
+
+将技能放在角色目录中，就只会在选中该角色时加载，无需填写 `skills` 字段：
+
+```text
+reviewer/
+├── config.json
+├── instructions.md
+└── skills/
+    └── code-review/
+        └── SKILL.md
+```
+
+### 主 Pi 的委派规则
+
+在 `~/.pi/agent/subagent/MAIN.md` 或受信任项目的 `.pi/subagent/MAIN.md` 中写入规则，例如：
+
+```markdown
+宣布任务完成之前，让 reviewer 审查本次代码变更。
+```
+
+这些指令只适用于主 Pi，不会加载到子助手中。主 Pi 和子助手都需要遵守的项目规则应放在 `AGENTS.md` 中。
+
+## 清理已删除会话的遗留文件
+
+执行 `/clean-sub`，立即删除找不到对应 Main ID 的运行时通信目录。它检查 Pi 默认会话目录和当前会话目录，始终保留当前 Main，不新增索引文件。会话文件无法读取或文件头无效时会停止清理，不会将它们当作已删除。
+
+持久化 Sub 的 `.jsonl` **不会自动删除**，请通过 Pi 的会话列表手动删除。角色配置和全局设置不受影响，命令也不会关闭 Herdr 标签页。如果移动过 Main 文件或使用其他自定义会话目录，请先确保这些会话位于扫描范围内，再执行清理。
+
+## 使用须知
+
+- **子助手依赖 Herdr。** 不支持无界面后台运行；最多同时打开四个子助手，子助手不能继续委派。
+- **角色配置不是沙箱。** 子助手以你的系统用户身份运行，配置“只读角色”不等于限制文件系统权限。
+- **MCP 沿用 Pi 的常规配置。** 角色只选择非 MCP 工具，不隔离或筛选 MCP 服务。自定义的非 MCP 工具必须来自主 Pi 已加载的扩展。
+- **子助手拥有独立对话。** 它会收到任务、角色配置和常规项目上下文，但不会收到主对话的聊天记录。请在任务中提供必要信息。
+- **重载主 Pi 不会关闭子助手。** 不再需要时请关闭标签页；异常崩溃后可能需要手动清理。
+
+如果找不到角色或启动失败，先运行 `/profiles`，检查目录名与 `name` 是否一致、项目是否受信任，以及引用的工具和技能是否可用。如果提示 Herdr 不可用，请确认 Pi 正在 Herdr 工作区内运行。
+
+如需在 Herdr 的 Agents 面板中隐藏或显示 Pi Subagent 子助手，可安装可选的 [Herdr 配套插件](herdr-plugin/README.md)（英文说明）。
+
+## 开发
+
+```bash
+npm install
+npm run check
+pi -e ./src/index.ts
+```
+
+维护者可参考[发布指南](docs/releasing.md)（英文），了解 CI 和 npm 自动发布流程。

package/docs/releasing.md

@@ -0,0 +1,61 @@
+# Releasing Pi Subagent
+
+Maintainer guide. For installation and usage, see the [README](../README.md).
+
+## CI and automatic npm releases
+
+GitHub Actions runs type checks, tests, package metadata validation, and a packaging dry run for pull requests and pushes to `main` and `dev`, on Node.js 22.19 and 24.
+
+A **version increase in `package.json` pushed to `main`** releases automatically after both check jobs pass:
+
+1. Validate the matching version in `package-lock.json`.
+2. Reserve `v<version>` at the exact checked commit.
+3. Publish the npm tarball through OIDC trusted publishing, with provenance.
+4. Create the GitHub Release with automatically generated release notes.
+
+Ordinary code/dependency changes with no version increase do not publish. Neither PRs, `dev` pushes, tag pushes, nor installing the workflow alone publish a package. Stable versions use npm's `latest` tag; prereleases such as `0.2.0-rc.1` use `next` and GitHub's prerelease flag.
+
+### One-time npm setup
+
+For a new package, publish the initial version once after committing and checking the source:
+
+```bash
+npm ci
+npm run check
+npm login
+npm publish --access public --ignore-scripts
+```
+
+This bootstrap publish creates the package so its trusted publisher can be configured. Subsequent releases use the workflow below, not local `npm publish`.
+
+In the npm settings for **@oldflag2333333/pi-subagent**, add a **GitHub Actions Trusted Publisher**:
+
+| Setting | Value |
+| --- | --- |
+| Organization or user | `oldflag2333333` |
+| Repository | `pi-subagent` |
+| Workflow filename | `release.yml` (filename only, not a path) |
+| Environment | Leave blank; this workflow does not use a GitHub Environment |
+| Allowed actions | Allow direct `npm publish` |
+
+No `NPM_TOKEN` secret is needed. GitHub supplies its built-in `GITHUB_TOKEN` for tags/releases; only the release job has `contents: write` and `id-token: write`. Publishing runs on a GitHub-hosted runner with Node 24 and a pinned npm 11 CLI. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) for package-side setup.
+
+Commit the workflow to GitHub and enable Actions before the first version bump. Keep `package.json`'s `repository.url` aligned with this repository; npm provenance and the release script verify that identity.
+
+### Releasing
+
+On your feature/release branch:
+
+```bash
+npm version minor --no-git-tag-version
+# Or: npm version patch --no-git-tag-version
+git add package.json package-lock.json
+git commit -m "chore: release v0.2.0"
+```
+
+Merge that change into `main` (or push it directly if your branch policy allows). The workflow handles the tag, npm publication, and GitHub Release; do not run `npm publish` yourself.
+
+If publishing fails, correct the external setup and **re-run the original failed workflow** on its original commit. An identical already-published artifact is not republished, so a failed GitHub Release step can be completed safely. An existing tag pointing elsewhere, an npm version with different contents, or a version that would move a dist-tag backwards causes an error instead of an overwrite. A failed npm publish may leave its reserved Git tag, but no GitHub Release is announced until publication succeeds. Publish one version at a time.
+
+GitHub Releases created by `GITHUB_TOKEN` do not trigger a second release workflow, so npm publication and Release creation deliberately run in the same job.
+

package/herdr-plugin/README.md

@@ -0,0 +1,34 @@
+# Pi Subagent Agent Visibility for Herdr
+
+This companion Herdr plugin hides Pi Subagent-managed subs from the built-in Agents panel by default and provides actions to show, hide, or toggle them.
+
+Pi Subagent marks each Herdr Sub pane with the metadata token `subagent_role=sub`. This plugin applies a transient `agent.view` filter; it does not affect `agent list`, notifications, lifecycle detection, or global attention counts.
+
+## Link for development
+
+```bash
+herdr plugin link /absolute/path/to/pi-subagent/herdr-plugin
+herdr plugin action invoke subagent.agent-visibility.hide-subs
+```
+
+## Actions
+
+```bash
+herdr plugin action invoke subagent.agent-visibility.toggle-subs
+herdr plugin action invoke subagent.agent-visibility.hide-subs
+herdr plugin action invoke subagent.agent-visibility.show-subs
+```
+
+The selected visibility is stored in `HERDR_PLUGIN_STATE_DIR` and restored when the Herdr server starts. The initial default is hidden.
+
+Optional keybinding:
+
+```toml
+[[keys.command]]
+key = "prefix+shift+a"
+type = "plugin_action"
+command = "subagent.agent-visibility.toggle-subs"
+description = "toggle Pi Subagent subs"
+```
+
+After editing Herdr config, run `herdr server reload-config`.

package/herdr-plugin/action.ts

@@ -0,0 +1,19 @@
+// @ts-nocheck
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { run } from "./index.mjs";
+
+// WORKAROUND: herdr-plugin.toml uses Pi with --list-models to load this action
+// without entering an interactive session. We run the visibility script during
+// extension initialization and exit before model listing, relying on Pi's startup
+// order. Prefer invoking index.mjs directly once Node availability is guaranteed
+// in the Herdr plugin environment.
+export default async function action(pi: ExtensionAPI): Promise<void> {
+	pi.registerFlag("subagent-visibility-action", {
+		description: "Internal Pi Subagent Herdr visibility action",
+		type: "string",
+	});
+	const flagIndex = process.argv.indexOf("--subagent-visibility-action");
+	const requested = flagIndex >= 0 ? process.argv[flagIndex + 1] : undefined;
+	await run(typeof requested === "string" && requested.length > 0 ? requested : "startup");
+	process.exit(0);
+}

package/herdr-plugin/herdr-plugin.toml

@@ -0,0 +1,27 @@
+id = "subagent.agent-visibility"
+name = "Pi Subagent Agent Visibility"
+version = "0.1.0"
+min_herdr_version = "0.8.2"
+description = "Hide or show Pi Subagent subs in Herdr's Agents panel"
+platforms = ["linux", "macos"]
+
+[[startup]]
+command = ["pi", "--offline", "--no-extensions", "-e", "action.ts", "--subagent-visibility-action", "startup", "--list-models"]
+
+[[actions]]
+id = "toggle-subs"
+title = "Toggle Pi Subagent subs"
+contexts = ["global"]
+command = ["pi", "--offline", "--no-extensions", "-e", "action.ts", "--subagent-visibility-action", "toggle", "--list-models"]
+
+[[actions]]
+id = "hide-subs"
+title = "Hide Pi Subagent subs"
+contexts = ["global"]
+command = ["pi", "--offline", "--no-extensions", "-e", "action.ts", "--subagent-visibility-action", "hide", "--list-models"]
+
+[[actions]]
+id = "show-subs"
+title = "Show Pi Subagent subs"
+contexts = ["global"]
+command = ["pi", "--offline", "--no-extensions", "-e", "action.ts", "--subagent-visibility-action", "show", "--list-models"]

package/herdr-plugin/index.mjs

@@ -0,0 +1,108 @@
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const pluginId = process.env.HERDR_PLUGIN_ID ?? "subagent.agent-visibility";
+const source = `plugin:${pluginId}`;
+const socketPath = process.env.HERDR_SOCKET_PATH;
+const stateDir = process.env.HERDR_PLUGIN_STATE_DIR;
+
+function statePath() {
+	if (!stateDir) throw new Error("HERDR_PLUGIN_STATE_DIR is missing.");
+	return path.join(stateDir, "visibility.json");
+}
+
+function readState() {
+	try {
+		const value = JSON.parse(fs.readFileSync(statePath(), "utf8"));
+		return { showSubs: value?.showSubs === true };
+	} catch (error) {
+		if (error?.code === "ENOENT") return { showSubs: false };
+		throw error;
+	}
+}
+
+function writeState(state) {
+	const file = statePath();
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	const temporary = `${file}.${process.pid}.tmp`;
+	fs.writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+	fs.renameSync(temporary, file);
+}
+
+function send(method, params) {
+	if (!socketPath) return Promise.reject(new Error("HERDR_SOCKET_PATH is missing."));
+	const endpoint = process.platform === "win32" ? `\\\\.\\pipe\\${socketPath}` : socketPath;
+	const request = { id: `subagent:${Date.now()}:${process.pid}`, method, params };
+	return new Promise((resolve, reject) => {
+		let buffer = "";
+		const socket = net.createConnection(endpoint);
+		const timeout = setTimeout(() => {
+			socket.destroy();
+			reject(new Error("Timed out waiting for Herdr."));
+		}, 5000);
+		const finish = (callback) => {
+			clearTimeout(timeout);
+			socket.destroy();
+			callback();
+		};
+		socket.on("error", (error) => finish(() => reject(error)));
+		socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));
+		socket.on("data", (chunk) => {
+			buffer += chunk.toString("utf8");
+			const newline = buffer.indexOf("\n");
+			if (newline < 0) return;
+			try {
+				const response = JSON.parse(buffer.slice(0, newline));
+				if (response.error) throw new Error(response.error.message ?? JSON.stringify(response.error));
+				finish(() => resolve(response.result));
+			} catch (error) {
+				finish(() => reject(error));
+			}
+		});
+	});
+}
+
+async function apply(showSubs) {
+	if (showSubs) {
+		await send("agent.view.clear", { source });
+		return;
+	}
+	await send("agent.view.set", {
+		source,
+		label: "subs hidden",
+		filter: {
+			op: "not",
+			filter: {
+				op: "eq",
+				field: { token: "subagent_role" },
+				value: "sub",
+			},
+		},
+		sort: [],
+	});
+}
+
+export async function run(action = "startup") {
+	const current = readState();
+	const next = action === "toggle"
+		? { showSubs: !current.showSubs }
+		: action === "show"
+			? { showSubs: true }
+			: action === "hide" || action === "startup"
+				? current
+				: undefined;
+	if (!next) throw new Error(`Unknown action '${action}'.`);
+	if (action === "hide") next.showSubs = false;
+	writeState(next);
+	await apply(next.showSubs);
+	console.log(next.showSubs ? "Pi Subagent subs are visible." : "Pi Subagent subs are hidden.");
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+	run(process.argv[2] ?? "startup").catch((error) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exitCode = 1;
+	});
+}