herdr-link 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-06
+
+### Added
+
+- **`herdr_link_start`**: a shared configured/explicit Agent start primitive for Pi, OpenCode, and MCP. Configured mode selects a complete entry from `.agents/agent_config.json`; explicit mode forwards complete `kind` and `args` without partial overrides or merge semantics.
+- Configured entries support one or more launch variants with opt-in `round-robin` selection, a process-local cursor isolated by project and config key, and no retry/fallback after a failed start.
+- Official `examples/agent_config.example.json` template and README guidance for project configuration and AI Agent decisions between configured and explicit start.
+
+### Changed
+
+- Project start configuration uses the standard JSON format and built-in `JSON.parse()`, providing a simple native configuration path for target projects.
+- Published the official configuration template through the npm package allowlist and added template/schema, package, and MCP working-directory coverage.
+
 ## [0.3.1] - 2026-09-01
 
 ### Changed

package/PROTOCOL.md

@@ -64,7 +64,7 @@ V1 不定义：`task_id`、`status`、`result`、`error`、`runtime`、`model`
 Herdr Link 的模型可见面分两个状态：
 
 - **Dormant**（默认）：Adapter 已注册但未激活。模型侧只呈现极小的 Tier 0 gateway（§4.1）；**不注入任何 Communication Contract**，不呈现 Tier 1 工具的完整 schema/description。
-- **Active**：Tier 0 gateway 被调用后（触发条件见 §6.2），Adapter 使本 runtime session 对模型呈现语义等价的 Active Contract，并使 peers/send/close 对模型可用；激活在本 runtime session 内保持，直到 session 结束。
+- **Active**：Tier 0 gateway 被调用后（触发条件见 §6.2），Adapter 使本 runtime session 对模型呈现语义等价的 Active Contract，并使 start/peers/send/close 对模型可用；激活在本 runtime session 内保持，直到 session 结束。
 
 Active 状态下，所有 Runtime Adapter 必须使本节规则的语义对 Agent 完整可见并暴露 §4 定义的能力。可通过 system-prompt injection、active tool schema/description、gateway presentation 或这些机制的组合实现；Active Contract 与工具 schema/description 共同构成完整且唯一的 Agent-facing 使用权威。符合规范的部署不得依赖外部 `AGENTS.md`、Skill、手工 prompt 或 Herdr CLI 指令补全正常通信知识。允许根据 Runtime 的呈现机制调整表现形式（例如 gateway dispatch 形态可将同名规则表达为对 `herdr_link` action 的说明），但以下规则不可改变：
 
@@ -89,7 +89,7 @@ Herdr Link is the standard interoperability channel between agents running in th
 ### 4.1 Tier 0：`herdr_link` gateway
 
 - 输入：`{}`（无参数）。
-- 输出：`{ "status": "active", "capabilities": ["peers", "send", "close"] }`。
+- 输出：`{ "status": "active", "capabilities": ["start", "peers", "send", "close"] }`。
 - 规范：
   1. gateway 是 dormant 状态下唯一的 Herdr Link discoverability surface；
   2. 幂等：重复调用仍返回 active；
@@ -97,7 +97,22 @@ Herdr Link is the standard interoperability channel between agents running in th
   4. gateway 本身不做 peer discovery、不发消息、不关 pane；
   5. 调用 gateway 不要求当前 Agent 已拥有 Agent Name。
 
-### 4.2 Tier 1：`herdr_link_peers`
+### 4.2 Tier 1：`herdr_link_start`
+
+> 在调用方已经决定启动 Agent 的前提下，在指定的现有 pane 中执行 Herdr `agent.start`。
+
+- 输入必须包含 `{ "name": string, "pane": string }`，并且只能选择以下一种完整参数来源：
+  - **配置模式**：增加 `config_agent: string`；从当前 runtime context 的 cwd 下 `.agents/agent_config.json` 读取 `agents[config_agent]`。
+  - **显式模式**：增加 `kind: string` 与 `args: string[]`；`kind + args` 原样作为 Herdr 启动参数。
+- `config_agent` 不得与 `kind` 或 `args` 同时出现；不支持 partial override 或 merge。
+- 配置文件是可选的；显式模式不读取配置文件。
+- 配置文件格式为 `version: 1` 与 `agents` 映射。每个 entry 必须有非空 `variants`；variant 必须有非空 `kind`，`args` 若存在必须为字符串数组。
+- 一个 entry 有多个 variants 时必须声明 `strategy: round-robin`；cursor 按项目配置与 `config_agent` 隔离，仅保存在当前进程内，并在启动成功后推进。
+- 每次配置模式调用都重新读取当前配置；启动失败不自动切换 variant、retry 或 fallback。
+- 首版只接受已有 pane，不负责创建 tab/pane 或规划 topology。
+- 输出：`{ "status": "started", "agent": string, "kind": string }`。
+
+### 4.3 Tier 1：`herdr_link_peers`
 
 - 输入：无。
 - 输出：
@@ -118,7 +133,7 @@ Herdr Link is the standard interoperability channel between agents running in th
   - 不返回 workspace_id / pane_id / tab_id / terminal ID；
   - `state` 仅供观察：不排序优先级、不解释业务含义、**不作为 send / close 的前置条件**。
 
-### 4.3 Tier 1：`herdr_link_send`
+### 4.4 Tier 1：`herdr_link_send`
 
 - 输入：`{ "to": string, "message": string }`；`to` 与 `message` 必须满足 §2.3；
 - 输出：`{ "status": "sent", "id": string, "to": string }`
@@ -129,7 +144,7 @@ Herdr Link is the standard interoperability channel between agents running in th
   - 不等待 reply；不自动 poll；不维护 pending request 状态；不执行 retry policy；
   - 投递给 Herdr `agent prompt` 的内容是 §2 所述的 self-describing inbound wrapper，Envelope 本身逐字不变。
 
-### 4.4 Tier 1：`herdr_link_close`
+### 4.5 Tier 1：`herdr_link_close`
 
 - 输入：`{ "agent": string }` —— 只接受 Agent Name，不接受 raw pane ID。
 - 正常输出：`{ "status": "closed", "agent": string }`
@@ -141,9 +156,9 @@ Herdr Link is the standard interoperability channel between agents running in th
   5. 如果关闭的是调用 Agent 自己的 pane，进程可能在工具响应完整返回前终止；调用方不得依赖 self-close 的返回值完成后续业务动作；
   6. Herdr 返回失败时直接失败，不猜测替代目标。
 
-### 4.5 工具命名呈现
+### 4.6 工具命名呈现
 
-- Canonical 名固定为 Tier 0 `herdr_link` 与 Tier 1 `herdr_link_peers` / `herdr_link_send` / `herdr_link_close`；
+- Canonical 名固定为 Tier 0 `herdr_link` 与 Tier 1 `herdr_link_start` / `herdr_link_peers` / `herdr_link_send` / `herdr_link_close`；
 - Runtime 可因宿主机制以不同形态呈现：
   - **true deferred tools**：四个工具均为独立注册工具，dormant 时仅 gateway 在模型可见集合中，激活后 Tier 1 进入可见集合（如 Pi 的动态工具 API）；
   - **prefix 型独立工具**（如 MCP 宿主的 `mcp__<namespace>__<tool>`）：呈现名的结尾必须是完整 canonical 名；
@@ -152,7 +167,7 @@ Herdr Link is the standard interoperability channel between agents running in th
 - 无论哪种形态，呈现层与 canonical 名之间必须有确定性映射；入参/出参 schema、错误语义与调用时序约束完全一致；
 - Active presentation 必须同时声明该 Runtime 的实际呈现方式与 dormant/active 行为，使模型无需猜测即可正确激活和调用。
 
-逻辑能力集合在所有形态下恒为：**activate / peers / send（包括普通回复）/ close**。
+逻辑能力集合在所有形态下恒为：**activate / start / peers / send（包括普通回复）/ close**。
 
 ## 5. Peer 地址模型与通信域
 
@@ -167,19 +182,19 @@ Herdr Link is the standard interoperability channel between agents running in th
 
 ## 6. Adapter Contract
 
-一个 Runtime 被视为支持 Herdr Link，必须由同一 Runtime Adapter 交付闭环满足四项逻辑能力：
+一个 Runtime 被视为支持 Herdr Link，必须由同一 Runtime Adapter 交付闭环满足五项逻辑能力：
 
 1. **Activate**：提供 `herdr_link` gateway 等价能力（§4.1）；
-2. **Expose Active Contract Semantics**：active 后让模型完整知道本协议第 3 节的规则；允许通过 system-prompt injection、active tool schema/description、gateway presentation 或组合实现；dormant 时必须**不**暴露 Tier 1 Contract 语义；
-3. **Expose Peers / Send**：提供 `herdr_link_peers`、`herdr_link_send`（包括普通回复）等价能力；
-4. **Expose Close**：提供 `herdr_link_close` 等价能力。
+2. **Start**：提供 `herdr_link_start` 等价能力（§4.2），只执行调用方明确提交的 configured 或 explicit start；
+3. **Expose Active Contract Semantics**：active 后让模型完整知道本协议第 3 节的规则；允许通过 system-prompt injection、active tool schema/description、gateway presentation 或组合实现；dormant 时必须**不**暴露 Tier 1 Contract 语义；
+4. **Expose Peers / Send**：提供 `herdr_link_peers`、`herdr_link_send`（包括普通回复）等价能力；
+5. **Expose Close**：提供 `herdr_link_close` 等价能力。
 
 “同一 Runtime Adapter”指一个可独立安装和验证的 Runtime-specific 交付单元；它可以由多个宿主接线点组成（例如 MCP tools + Runtime hook），但不得把外部 Agent 指令文件或操作者维护的 Contract 副本当作第五项依赖。
 
-Adapter 可通过 Extension、Hook、Plugin、MCP Tool 或 Runtime 原生 tool system 实现；不强制实现语言。V1 不创建统一 Adapter Framework（无 BaseAdapter / registry / plugin loader / daemon）。工具命名呈现须符合 §4.5。已知的合规呈现形态：
-
+Adapter 可通过 Extension、Hook、Plugin、MCP Tool 或 Runtime 原生 tool system 实现；不强制实现语言。V1 不创建统一 Adapter Framework（无 BaseAdapter / registry / plugin loader / daemon）。工具命名呈现须符合 §4.6。已知的合规呈现形态：
 - **true deferred tools**（如 Pi）：四工具全部注册，`session_start` 时把 Tier 1 移出 active 集合，gateway 以加性方式启用 Tier 1；close 保持顺序执行以保证 send 先完成；
-- **single-gateway dispatch**（宿主无公开的动态启停 API 时，如 OpenCode）：模型面常驻且仅有一个极小 `herdr_link` dispatcher，空参调用幂等激活本 session，随后以 `action: peers|send|close` 分发到同一控制层；Active Contract semantics 仅在已激活 session 暴露；
+- **single-gateway dispatch**（宿主无公开的动态启停 API 时，如 OpenCode）：模型面常驻且仅有一个极小 `herdr_link` dispatcher，空参调用幂等激活本 session，随后以 `action: start|peers|send|close` 分发到同一控制层；Active Contract semantics 仅在已激活 session 暴露；
 - **shared MCP：listChanged 优先 + gateway fallback**（Claude Code / Codex / AGY 等）：dormant `tools/list` 只返回 gateway；声明 `tools.listChanged` capability，激活时发射一次 `notifications/tools/list_changed`；active `tools/list` 返回 gateway + Tier 1；不响应刷新的 Host 通过 gateway 显式 action 分发保持全功能。MCP activation 按 stdio 连接（即宿主为本 session 拉起的 server 进程）记忆，连接结束即回到 dormant。
 
 ### 6.1 环境门控（Environment Gate）
@@ -217,24 +232,29 @@ V1 定义最小错误语义，全部是本地 tool operation failure，不是跨
 | `PEER_NOT_FOUND` | 目标不是当前 workspace 内的 live named peer——涵盖名字非法、目标不存在、目标属于其他 workspace、target workspace 未上报；四种情况对模型不可区分（scope privacy） |
 | `SEND_FAILED` | self 与目标均已解析并通过 guard，但 Herdr 未接受 message prompt |
 | `CLOSE_FAILED` | 目标已解析到 authoritative pane，但 Herdr `pane close` 失败 |
+| `START_CONFIG_NOT_FOUND` | 配置模式找不到当前项目的 `.agents/agent_config.json` |
+| `START_AGENT_NOT_FOUND` | `config_agent` 不存在于配置的 `agents` 映射 |
+| `START_CONFIG_INVALID` | 配置 JSON、schema、variants 或 strategy 非法 |
+| `START_INPUT_INVALID` | configured/explicit 输入缺失、类型错误或字段混用 |
+| `START_FAILED` | Herdr `agent.start` 拒绝或启动失败 |
 
 ### Failure Policy
 
 - 不自动 retry；不 fallback 到 terminal send/read；不 fallback 到 focused pane；不转换成 Workflow 状态；
-- **错误分类透传**：底层已归类为 `NOT_IN_HERDR` 的环境/transport 失败，不得被外层操作逻辑重包装成 `SEND_FAILED` / `CLOSE_FAILED` 等操作级错误码；操作逻辑只对尚未分类的意外异常使用自身 fallback 码；
+- **错误分类透传**：底层已归类为 `NOT_IN_HERDR` 的环境/transport 失败，不得被外层操作逻辑重包装成 `START_FAILED` / `SEND_FAILED` / `CLOSE_FAILED` 等操作级错误码；操作逻辑只对尚未分类的意外异常使用自身 fallback 码；
 - Agent-facing tool error 只返回稳定 error code 与简化原因；不得暴露 raw pane/tab/workspace/terminal ID，也不得把 `agent rename` 或其他越界恢复动作提示给模型。底层诊断细节如需保留，只能进入 operator-facing 日志。
 
 ## 8. Command Safety
 
 - Herdr CLI 必须通过 argv 数组执行（`execFile` 或等价无 shell 方式），禁止构造 shell command string。
-- 调用面：`agent get <target>`、`agent list`、`agent prompt <target> <text>`、`pane close <pane_id>`。
+- 调用面：`agent get <target>`、`agent list`、`agent prompt <target> <text>`、`agent start <name> --kind <kind> --pane <pane> -- [args...]`、`pane close <pane_id>`。
 - `agent prompt` 的投递文本是 §2 定义的 self-describing inbound wrapper；除此之外不构造任何额外协议负载。
-- 不使用 `--wait`（V1 无订阅、无等待语义）。不调用：`agent.wait`、`agent.read`、`pane.read`、`events.subscribe`、`pane.send_text`、`pane.send_keys`、`agent start`、任何 workspace 控制命令。
+- 不使用 `--wait`（V1 无订阅、无等待语义）。不调用：`agent.wait`、`agent.read`、`pane.read`、`events.subscribe`、`pane.send_text`、`pane.send_keys`、任何 workspace 控制命令；`agent start` 只能由 canonical `herdr_link_start` 进入。
 - `agent rename` 仅限 §6.3 self identity bootstrap 使用：目标只能是当前 pane 中未命名的 live occupant；禁止将其暴露为模型工具、用于任何其他 pane/agent 目标，或在面向模型的文本中提示该动作。
 
 ## 9. Non-goals
 
-V1 不提供：agent 创建/启动/配置/调度、通用 Agent Name 管理（分配策略/持久化/恢复——§6.3 的一次性 self identity bootstrap 除外，Link 自身不持久化任何名字）、自动回收策略、模型选择、workflow/task/stage 状态、业务结果 schema、evidence/receipt/review、持久消息队列、跨机器传输、权限审批系统、离线投递、可靠投递确认、全局权限、跨 session 持久化。
+V1 提供调用方明确请求的 Agent start execution primitive（configured/explicit），但不提供业务调度、任务编排、Agent pool、持久化配置状态或模型选择策略。Link 仍不提供通用 Agent Name 管理（分配策略/持久化/恢复——§6.3 的一次性 self identity bootstrap 除外，Link 自身不持久化任何名字）、自动回收策略、workflow/task/stage 状态、业务结果 schema、evidence/receipt/review、持久消息队列、跨机器传输、权限审批系统、离线投递、可靠投递确认、全局权限或跨 session 持久化。
 
 明确不属于 Herdr Link 的还有：
 

package/README.md

@@ -7,7 +7,7 @@
 
 **English** | [简体中文](./README.zh-CN.md)
 
-Herdr Link is an on-demand cross-agent interoperability layer running inside Herdr sessions. Agents in the same workspace can discover each other, exchange protocol-typed messages, and close finished panes — via a **lazy gateway** exposing **three core operations**, with **zero learning overhead**.
+Herdr Link is an on-demand cross-agent interoperability layer running inside Herdr sessions. Agents in the same workspace can start an explicitly requested Agent, discover each other, exchange protocol-typed messages, and close finished panes — via a **lazy gateway** exposing **four core operations**, with **zero learning overhead**.
 
 Adapters are provided for Pi (native extension), OpenCode (plugin bundle), and any MCP-capable runtime such as Claude Code, Codex, or AGY (shared stdio MCP server). The wire format is the `herdr-link/1` protocol, specified canonically in [`PROTOCOL.md`](./PROTOCOL.md).
 
@@ -19,7 +19,7 @@ The usual way to teach agents cross-agent messaging is to point them at the offi
 - that reasoning **consumes tokens and adds latency on every use**;
 - usage knowledge is **re-derived by the model** instead of being given to it.
 
-Herdr Link removes that step entirely. The adapter hands the model three core operations behind a lazy gateway and injects a compact communication contract automatically:
+Herdr Link removes that step entirely. The adapter hands the model four core operations behind a lazy gateway and injects a compact communication contract automatically:
 
 | | Official Herdr Skill route | With Herdr Link |
 |---|---|---|
@@ -31,7 +31,7 @@ Herdr Link removes that step entirely. The adapter hands the model three core op
 In short:
 
 - **Fewer tokens.** Nothing to read or figure out. While dormant, the model sees only a tiny `herdr_link` gateway — no contract, no schemas. After activation it gets one short contract, not a manual.
-- **Faster communication.** Discover peers, send a protocol-typed message, or close a pane is a single direct tool call — no multi-step CLI orchestration in between.
+- **Faster control.** Start an Agent, discover peers, send a protocol-typed message, or close a pane with a direct tool call — no multi-step CLI orchestration in between.
 - **Effortless ("zero-reasoning") integration.** Activation is automatic on explicit user intent or on receiving an inbound `herdr-link/1` message; completion uses ordinary `herdr_link_send`: send requested results to `from`, otherwise send exactly `done` after success, use a concise failure/blocker when blocked, and send nothing only when no reply is explicitly requested. `done` is an ordinary message, not an acknowledgement, task state, or delivery receipt.
 
 ## How it works
@@ -40,6 +40,8 @@ Every runtime exposes the same lazy two-tier surface:
 
 ```text
 Agent A → herdr_link {}                    # activate (idempotent)
+Agent A → herdr_link_start(name, pane, config_agent) # configured start
+Agent A → herdr_link_start(name, pane, kind, args)         # explicit start
 Agent A → herdr_link_send(to="B", ...)     # status "sent"
 Agent B → (receives inbound wrapper) herdr_link {}   # auto-activation trigger
 Agent B → herdr_link_send(to="A", message="result or done")
@@ -47,9 +49,106 @@ Anyone  → herdr_link_close(agent="worker-a")   # in a later tool step after th
 ```
 
 - **Dormant tier:** only the `herdr_link` gateway is visible; calling it with `{}` activates the session once (idempotent, in-memory only).
-- **Active tier:** `herdr_link_peers`, `herdr_link_send`, `herdr_link_close`, plus the compact Communication Contract. Every call re-resolves live identity/workspace via Herdr and enforces a same-workspace guard.
+- **Active tier:** `herdr_link_start`, `herdr_link_peers`, `herdr_link_send`, `herdr_link_close`, plus the compact Communication Contract. Every communication call re-resolves live identity/workspace via Herdr and enforces a same-workspace guard.
 
-Herdr Link does not decide what agents should do, and it does not create, schedule, model-select, or recycle agents. It is purely the messaging layer.
+## Starting Agents
+
+> `herdr_link_start` only executes an already-decided start; it does not choose a business role or create a pane.
+
+### Project start configuration
+
+The project-level configuration is optional and has one fixed location:
+
+```text
+<project-root>/.agents/agent_config.json
+```
+
+The official template is included in both the GitHub repository and the npm package at:
+
+```text
+examples/agent_config.example.json
+```
+
+To use the template in a target project:
+
+```bash
+mkdir -p .agents
+cp /path/to/agent_config.example.json .agents/agent_config.json
+```
+
+The copy command is only a convenience; the complete schema is also shown here so npm users do not need to know the package's installation directory:
+
+```json
+{
+  "version": 1,
+  "agents": {
+    "example-single": {
+      "variants": [
+        {
+          "kind": "pi",
+          "args": [
+            "--model",
+            "your-provider/your-model",
+            "--thinking",
+            "high"
+          ]
+        }
+      ]
+    },
+    "example-round-robin": {
+      "strategy": "round-robin",
+      "variants": [
+        {
+          "kind": "pi",
+          "args": [
+            "--model",
+            "provider-a/model-a",
+            "--thinking",
+            "high"
+          ]
+        },
+        {
+          "kind": "pi",
+          "args": [
+            "--model",
+            "provider-b/model-b",
+            "--thinking",
+            "high"
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+Use configured start for a reusable launch choice: `{"name":"worker-01","pane":"wS:p22","config_agent":"example-single"}`. The `config_agent` value is a user-defined key under `agents`; Herdr Link does not interpret its business meaning.
+
+Use explicit start for a one-off launch, without changing the project file: `{"name":"worker-01","pane":"wS:p22","kind":"pi","args":["--model","model-x","--thinking","high"]}`. The two modes are mutually exclusive; a configured call cannot partially override `kind` or `args`.
+
+#### Configuration rules for humans and AI Agents
+
+When a human or an AI Agent creates or edits `.agents/agent_config.json`:
+
+1. Save a long-term or repeatable launch choice under `agents.<config-key>`.
+2. Choose a project-defined key such as `work-agent`, `reviewer`, `research-agent`, or `fast-worker`; Herdr Link does not assign business meaning to it.
+3. Give every configured entry at least one complete `variant`.
+4. Every variant must have a non-empty `kind`.
+5. If present, `args` must be a string array passed directly after `herdr agent start ... --`.
+6. A single variant needs no `strategy`.
+7. Multiple variants require `"strategy": "round-robin"`.
+8. Do not create a half-filled entry expecting `herdr_link_start` to complete it at runtime; partial override, merge, and guessed values are unsupported.
+9. If the user asks for launch parameters only this time, do not edit the config; use explicit start.
+10. Persistent preferences such as “use this by default” or “rotate this worker between A and B” are appropriate reasons to edit the config.
+
+The decision is:
+
+| User intent | Project file | Start mode |
+|---|---|---|
+| Long-term / repeatable launch choice | Write `.agents/agent_config.json` | configured |
+| One-off / temporary launch parameters | Do not change the file | explicit |
+
+Herdr Link does not decide what agents should do, does not create panes, schedule work, select models, or recycle agents. Its `start` capability only executes a caller-provided configured or explicit launch choice; the remaining capabilities are the messaging layer.
 
 ## Installation
 
@@ -84,7 +183,7 @@ cp src/herdr.ts src/protocol.ts ~/.pi/agent/extensions/herdr-link/
 # or: pi --extension /path/to/herdr-link/src/pi.ts
 ```
 
-After installation the adapter registers the `herdr_link` gateway plus the three Tier 1 tools; Tier 1 starts inactive each session and is enabled (with contract injection) when the model calls `herdr_link {}`.
+After installation the adapter registers the `herdr_link` gateway plus the four Tier 1 tools; Tier 1 starts inactive each session and is enabled (with contract injection) when the model calls `herdr_link {}`.
 
 ### OpenCode (single-file plugin)
 
@@ -96,11 +195,11 @@ cp "$(npm root -g)/herdr-link/dist/herdr-link.opencode.js" \
    ~/.config/opencode/plugins/herdr-link.js
 ```
 
-OpenCode has no per-session tool toggle API, so the adapter presents a **single-gateway dispatcher**: `{}` activates, then `{"action":"peers"|"send"|"close", ...}` dispatches to the same control layer. The contract is injected into the system prompt of activated sessions only (in-memory per `sessionID`; a server restart returns to dormant).
+OpenCode has no per-session tool toggle API, so the adapter presents a **single-gateway dispatcher**: `{}` activates, then `{"action":"start"|"peers"|"send"|"close", ...}` dispatches to the same control layer. Start accepts either `name + pane + config_agent` or complete `name + pane + kind + args`; the modes do not merge. The contract is injected into the system prompt of activated sessions only (in-memory per `sessionID`; a server restart returns to dormant).
 
 ### Claude Code / Codex / AGY (shared stdio MCP server)
 
-Runtimes without a native custom-tool API all share the same zero-dependency stdio MCP server, published as this package's `bin`:
+Runtimes without a native custom-tool API all share the same stdio MCP server (no MCP SDK dependency; configuration uses Node's built-in `JSON.parse`), published as this package's `bin`:
 
 ```bash
 npx -y herdr-link           # starts the MCP server on stdio
@@ -123,7 +222,7 @@ The runtime process must be started by Herdr in a managed pane:
 - Outside a Herdr pane every adapter is a complete no-op: Pi/OpenCode register nothing, MCP returns an empty tool list.
 - In a Herdr pane while dormant, only the `herdr_link` gateway is visible to the model.
 - **Self identity bootstrap** (PROTOCOL.md §6.3): a manually started agent that is recognized by Herdr but has no valid Agent Name is named automatically with a generated `hl-*` name (`ensureSelfName()` at adapter startup plus a fallback inside every communication path). Existing names are never rewritten, nothing is persisted; if the bootstrap fails the Link errors with `SELF_UNNAMED`.
-- Runtime failures come back as Link errors (`NOT_IN_HERDR` / `SELF_UNNAMED` / `PEER_NOT_FOUND` / `SEND_FAILED` / `CLOSE_FAILED`).
+- Runtime failures come back as Link errors (`NOT_IN_HERDR` / `SELF_UNNAMED` / `PEER_NOT_FOUND` / `SEND_FAILED` / `CLOSE_FAILED` / `START_CONFIG_NOT_FOUND` / `START_AGENT_NOT_FOUND` / `START_CONFIG_INVALID` / `START_INPUT_INVALID` / `START_FAILED`).
 
 ## Error model
 
@@ -134,6 +233,11 @@ The runtime process must be started by Herdr in a managed pane:
 | `PEER_NOT_FOUND` | Target is not a live named peer in the current workspace (nonexistent / invalid name / other workspace — indistinguishable to the model) |
 | `SEND_FAILED` | Herdr did not accept the message prompt although guards passed |
 | `CLOSE_FAILED` | Target resolved to a pane but Herdr's pane close failed |
+| `START_CONFIG_NOT_FOUND` | Configured mode could not find `.agents/agent_config.json` |
+| `START_AGENT_NOT_FOUND` | `config_agent` is absent from the config's `agents` map |
+| `START_CONFIG_INVALID` | JSON, schema, variants, or strategy is invalid |
+| `START_INPUT_INVALID` | Start fields are missing, mistyped, or mixed across modes |
+| `START_FAILED` | Herdr rejected or failed to start the Agent |
 
 Errors are local tool failures, not inter-agent message types; Link provides no acknowledgement, wait, poll, task/pending state, auto-retry, or fallback.
 
@@ -154,7 +258,7 @@ Layout:
 ```text
 PROTOCOL.md                  canonical protocol spec (envelope, tiers, contract, semantics, errors)
 src/protocol.ts              protocol core: types, envelope/wrapper builders, errors, COMMUNICATION_CONTRACT
-src/herdr.ts                 Herdr CLI control layer: live identity/workspace resolution, same-workspace guard
+src/herdr.ts                 Herdr CLI control layer: configured/explicit Agent start, JSON config parsing, cursor, live identity/workspace resolution
 src/pi.ts                    Pi adapter: gateway + deferred Tier 1 (setActiveTools), post-activation contract injection
 src/opencode.ts              OpenCode adapter: single-gateway dispatcher + per-sessionID contract injection
 src/mcp.ts                   shared stdio MCP server: JSON-RPC, lazy tool list, gateway dispatch
@@ -165,9 +269,9 @@ scripts/mcp-probe.mjs        stdio handshake debugging probe
 
 Layering rule: `protocol.ts` has zero Herdr IO; `herdr.ts` only drives the Herdr control plane (`execFile` argv arrays, no shell); `pi.ts` / `opencode.ts` / `mcp.ts` only do runtime wiring. Activation state lives in memory per runtime session: never persisted, never restored across sessions.
 
-## Scope and non-goals (V1)
+## Scope and non-goals
 
-Herdr Link is a same-workspace messaging/interoperability layer, not an agent lifecycle or task-management system. It does not provide agent creation/scheduling/recycling, model selection, workflow/task/stage state, business result schemas or evidence/receipt/review, acknowledgement/wait/poll/retry/pending-request semantics or reliable-delivery guarantees, persistent queues or cross-session persistence, cross-machine transport, permission approval, offline delivery, **cross-workspace discovery/send/close** (that belongs to the official Herdr Skill / CLI control plane), or workspace/topology management. Put business payloads in the `message` field; Link never interprets their semantics. See [`PROTOCOL.md` §9](./PROTOCOL.md#9-non-goals) for the canonical scope.
+Herdr Link is a same-workspace interoperability layer, not a business scheduler or task-management system. It provides only an explicit configured/explicit Agent start execution primitive; it does not choose roles, create or plan panes, schedule/recycle agents, select models, manage workflow/task/stage state, define business result schemas or evidence/receipt/review, provide acknowledgement/wait/poll/retry/pending-request semantics or reliable-delivery guarantees, maintain persistent queues or cross-session state, perform cross-machine transport, permission approval, offline delivery, **cross-workspace discovery/send/close** (that belongs to the official Herdr Skill / CLI control plane), or manage workspace topology. Put business payloads in the `message` field; Link never interprets their semantics. See [`PROTOCOL.md` §9](./PROTOCOL.md#9-non-goals) for the canonical scope.
 
 ## License
 

package/README.zh-CN.md

@@ -7,7 +7,7 @@
 
 [English](./README.md) | **简体中文**
 
-Herdr Link 是运行在 Herdr 会话中的跨 Agent 按需互操作层。同一 workspace 内的 Agent 可以互相发现、交换协议化消息、关闭已完成的 pane——通过一个 **lazy gateway** 暴露 **3 项核心能力**，**零学习成本**。
+Herdr Link 是运行在 Herdr 会话中的跨 Agent 按需互操作层。同一 workspace 内的 Agent 可以按调用方明确选择启动 Agent、互相发现、交换协议化消息、关闭已完成的 pane——通过一个 **lazy gateway** 暴露 **4 项核心能力**，**零学习成本**。
 
 提供 Pi（原生扩展）、OpenCode（插件 bundle）以及任意支持 MCP 的 Runtime 如 Claude Code / Codex / AGY（共享 stdio MCP server）的 Adapter。线上格式为 `herdr-link/1` 协议，唯一规范见 [`PROTOCOL.md`](./PROTOCOL.md)。
 
@@ -19,7 +19,7 @@ Herdr Link 是运行在 Herdr 会话中的跨 Agent 按需互操作层。同一
 - 这些推理过程**每次使用都在消耗 token 并增加延迟**；
 - 使用知识靠模型**反复自行推导**，而不是直接交给它。
 
-Herdr Link 把这一步彻底去掉。Adapter 通过一个惰性 gateway 暴露 3 项核心能力，并自动注入一份紧凑的通信契约：
+Herdr Link 把这一步彻底去掉。Adapter 通过一个惰性 gateway 暴露 4 项核心能力，并自动注入一份紧凑的通信契约：
 
 | | 官方 Herdr Skill 路线 | 使用 Herdr Link |
 |---|---|---|
@@ -31,7 +31,7 @@ Herdr Link 把这一步彻底去掉。Adapter 通过一个惰性 gateway 暴露
 一句话总结：
 
 - **更少消耗。** 无需阅读、无需推导。dormant 态下模型只看到一个极小的 `herdr_link` gateway——无契约、无 schema；激活后也只注入一段简短契约，而不是一本手册。
-- **更快通讯。** 发现对端、发送协议化消息、关闭 pane 都是一次直接的工具调用——中间没有任何多步 CLI 编排。
+- **更快控制。** 启动 Agent、发现对端、发送协议化消息或关闭 pane 都是一次直接的工具调用——中间没有任何多步 CLI 编排。
 - **无感接入（零推理）。** 用户显式提出 Herdr 需求、或收到 inbound `herdr-link/1` 消息时自动激活；完成通过普通的 `herdr_link_send`：将指定结果发给 `from`；未指定结果时成功后精确发送 `done`；失败/阻塞时发送简短说明；只有明确要求不回复时才不发送。`done` 只是普通消息，不是 ACK、任务状态或投递回执。
 
 ## 工作方式
@@ -40,6 +40,8 @@ Herdr Link 把这一步彻底去掉。Adapter 通过一个惰性 gateway 暴露
 
 ```text
 Agent A → herdr_link {}                    # 激活（幂等）
+Agent A → herdr_link_start(name, pane, config_agent) # 配置模式
+Agent A → herdr_link_start(name, pane, kind, args)         # 显式模式
 Agent A → herdr_link_send(to="B", ...)     # status "sent"
 Agent B → （收到 inbound wrapper）herdr_link {}   # 自动激活触发
 Agent B → herdr_link_send(to="A", message="结果或 done")
@@ -47,9 +49,106 @@ Agent B → herdr_link_send(to="A", message="结果或 done")
 ```
 
 - **Dormant 层**：只有 `herdr_link` gateway 可见；空参 `{}` 调用一次性激活当前 session（幂等、纯内存态）。
-- **Active 层**：`herdr_link_peers`、`herdr_link_send`、`herdr_link_close`，外加紧凑 Communication Contract。每次调用都经 Herdr 实时解析身份/workspace 并执行同 workspace guard。
+- **Active 层**：`herdr_link_start`、`herdr_link_peers`、`herdr_link_send`、`herdr_link_close`，外加紧凑 Communication Contract。每次通信调用都经 Herdr 实时解析身份/workspace 并执行同 workspace guard。
 
-Herdr Link 不决定 Agent 应该做什么，也不负责 Agent 的创建、调度、模型选择或回收——它只是消息层。
+## 启动 Agent
+
+> `herdr_link_start` 只执行调用方已经作出的启动选择，不选择业务角色，也不创建 pane。
+
+### 项目级 start 配置
+
+项目级配置是可选的，固定位置为：
+
+```text
+<project-root>/.agents/agent_config.json
+```
+
+GitHub 仓库和 npm 包都包含官方模板：
+
+```text
+examples/agent_config.example.json
+```
+
+在目标项目中使用模板：
+
+```bash
+mkdir -p .agents
+cp /path/to/agent_config.example.json .agents/agent_config.json
+```
+
+复制命令只是便利方式；下面同时给出完整 schema，因此 npm 用户不需要知道包实际安装目录：
+
+```json
+{
+  "version": 1,
+  "agents": {
+    "example-single": {
+      "variants": [
+        {
+          "kind": "pi",
+          "args": [
+            "--model",
+            "your-provider/your-model",
+            "--thinking",
+            "high"
+          ]
+        }
+      ]
+    },
+    "example-round-robin": {
+      "strategy": "round-robin",
+      "variants": [
+        {
+          "kind": "pi",
+          "args": [
+            "--model",
+            "provider-a/model-a",
+            "--thinking",
+            "high"
+          ]
+        },
+        {
+          "kind": "pi",
+          "args": [
+            "--model",
+            "provider-b/model-b",
+            "--thinking",
+            "high"
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+需要长期复用的启动方式使用 configured start：`{"name":"worker-01","pane":"wS:p22","config_agent":"example-single"}`。`config_agent` 是 `agents` 下由项目自行定义的 key，Herdr Link 不解释其业务含义。
+
+一次性启动使用 explicit start，不修改项目配置：`{"name":"worker-01","pane":"wS:p22","kind":"pi","args":["--model","model-x","--thinking","high"]}`。两种模式严格互斥；配置调用不能只覆盖 `kind` 或 `args`。
+
+#### 人类用户与 AI Agent 的配置规则
+
+人类用户或 AI Agent 创建、修改 `.agents/agent_config.json` 时：
+
+1. 长期或重复使用的启动方式写入 `agents.<config-key>`。
+2. `<config-key>` 由项目自行命名，例如 `work-agent`、`reviewer`、`research-agent`、`fast-worker`；Herdr Link 不赋予它业务含义。
+3. 每个 configured entry 至少包含一个完整的 `variant`。
+4. 每个 variant 必须包含非空 `kind`。
+5. `args` 如果存在，必须是字符串数组，并直接放在 `herdr agent start ... --` 之后传递。
+6. 只有一个 variant 时不需要 `strategy`。
+7. 多个 variants 必须使用 `"strategy": "round-robin"`。
+8. 不要创建半填写 entry 并期待 `herdr_link_start` 运行时补齐；不支持 partial override、merge 或猜测缺失值。
+9. 用户只要求这一次使用某组参数时，不要修改配置文件，应使用 explicit start。
+10. “以后默认这样启动”或“以后让这个 worker 在 A/B 之间轮换”等持久偏好，才适合修改配置文件。
+
+决策关系：
+
+| 用户意图 | 项目文件 | 启动模式 |
+|---|---|---|
+| 长期 / 重复启动方式 | 写入 `.agents/agent_config.json` | configured |
+| 一次性 / 临时启动参数 | 不修改文件 | explicit |
+
+Herdr Link 不决定 Agent 应该做什么，也不创建 pane、调度工作、选择模型或回收 Agent。`start` 只执行调用方提交的配置或显式启动选择；其余能力是消息层。
 
 ## 安装
 
@@ -72,7 +171,7 @@ cp src/herdr.ts src/protocol.ts ~/.pi/agent/extensions/herdr-link/
 # 或：pi --extension /path/to/herdr-link/src/pi.ts
 ```
 
-安装后 Adapter 注册 `herdr_link` gateway 与三个 Tier 1 工具；每个 session 开始时 Tier 1 处于 inactive，模型调用 `herdr_link {}` 后启用并注入契约。
+安装后 Adapter 注册 `herdr_link` gateway 与四个 Tier 1 工具；每个 session 开始时 Tier 1 处于 inactive，模型调用 `herdr_link {}` 后启用并注入契约。
 
 ### OpenCode（单文件插件）
 
@@ -84,11 +183,11 @@ cp "$(npm root -g)/herdr-link/dist/herdr-link.opencode.js" \
    ~/.config/opencode/plugins/herdr-link.js
 ```
 
-OpenCode 没有按 session 启停工具的 API，因此 Adapter 采用**single-gateway dispatcher** 呈现：`{}` 激活，之后 `{"action":"peers"|"send"|"close", ...}` 分发到同一控制层。契约只注入已激活 session 的 system prompt（按 `sessionID` 记忆的内存态；server 重启回到 dormant）。
+OpenCode 没有按 session 启停工具的 API，因此 Adapter 采用**single-gateway dispatcher** 呈现：`{}` 激活，之后 `{"action":"start"|"peers"|"send"|"close", ...}` 分发到同一控制层。`start` 使用 `name + pane + config_agent` 或完整的 `name + pane + kind + args`，两种模式不合并。契约只注入已激活 session 的 system prompt（按 `sessionID` 记忆的内存态；server 重启回到 dormant）。
 
 ### Claude Code / Codex / AGY（共享 stdio MCP server）
 
-没有原生自定义工具注册面的 Runtime 共用同一个零依赖 stdio MCP server，以本包的 `bin` 发布：
+没有原生自定义工具注册面的 Runtime 共用同一个 stdio MCP server（不依赖 MCP SDK，配置使用 Node 原生 `JSON.parse`），以本包的 `bin` 发布：
 
 ```bash
 npx -y herdr-link           # 在 stdio 上启动 MCP server
@@ -111,7 +210,7 @@ MCP 同样是惰性呈现：非 Herdr 环境 `tools/list` 返回空集；Herdr m
 - 非 Herdr managed pane 中所有 Adapter 均为完全 no-op：Pi/OpenCode 不注册任何工具，MCP 返回空工具集；
 - Herdr 环境 dormant 态下，模型侧只有 `herdr_link` gateway 可见；
 - **Self identity bootstrap**（PROTOCOL.md §6.3）：用户手动启动、已被 Herdr 识别但尚无合法 Agent Name 的 agent，会被自动赋一个生成的 `hl-*` 名字（Adapter 启动时执行一次 `ensureSelfName()`，通信路径内另有 fallback）。已有名字绝不改写、不持久化；bootstrap 失败时 Link 以 `SELF_UNNAMED` 报错；
-- 运行期失败通过 Link error 返回（`NOT_IN_HERDR` / `SELF_UNNAMED` / `PEER_NOT_FOUND` / `SEND_FAILED` / `CLOSE_FAILED`）。
+- 运行期失败通过 Link error 返回（`NOT_IN_HERDR` / `SELF_UNNAMED` / `PEER_NOT_FOUND` / `SEND_FAILED` / `CLOSE_FAILED` / `START_CONFIG_NOT_FOUND` / `START_AGENT_NOT_FOUND` / `START_CONFIG_INVALID` / `START_INPUT_INVALID` / `START_FAILED`）。
 
 ## 错误模型
 
@@ -122,6 +221,11 @@ MCP 同样是惰性呈现：非 Herdr 环境 `tools/list` 返回空集；Herdr m
 | `PEER_NOT_FOUND` | 目标不是当前 workspace 内的 live named peer（不存在/非法名/其他 workspace——对模型不可区分） |
 | `SEND_FAILED` | guard 通过后 Herdr 未接受 message prompt |
 | `CLOSE_FAILED` | 目标已解析到 pane，但 Herdr pane close 失败 |
+| `START_CONFIG_NOT_FOUND` | 配置模式找不到 `.agents/agent_config.json` |
+| `START_AGENT_NOT_FOUND` | `config_agent` 不在配置的 `agents` 映射中 |
+| `START_CONFIG_INVALID` | JSON、schema、variants 或 strategy 非法 |
+| `START_INPUT_INVALID` | start 字段缺失、类型错误或两种模式混用 |
+| `START_FAILED` | Herdr 拒绝或启动 Agent 失败 |
 
 错误是本地 tool failure，不是跨 Agent 消息类型；Link 不提供 ACK、wait、poll、task/pending 状态、自动重试或 fallback。
 
@@ -142,7 +246,7 @@ npm run build:mcp           # dist/herdr-link.mcp.js
 ```text
 PROTOCOL.md                  协议唯一规范（Envelope、两级能力面、Contract、工具语义、错误模型）
 src/protocol.ts              协议核心：类型、envelope/wrapper 构建、错误、COMMUNICATION_CONTRACT
-src/herdr.ts                 Herdr CLI 控制层：live identity/workspace 解析、same-workspace guard
+src/herdr.ts                 Herdr CLI 控制层：configured/explicit Agent start、JSON 配置解析、cursor、live identity/workspace 解析
 src/pi.ts                    Pi Runtime Adapter：gateway + deferred Tier 1（setActiveTools），激活后注入契约
 src/opencode.ts              OpenCode Runtime Adapter：single-gateway dispatcher + 按 sessionID 契约注入
 src/mcp.ts                   共享 stdio MCP server：JSON-RPC、惰性工具列表、gateway dispatch
@@ -153,9 +257,9 @@ scripts/mcp-probe.mjs        stdio 握手排障探针
 
 分层原则：`protocol.ts` 零 Herdr IO；`herdr.ts` 只做 Herdr 控制面调用（`execFile` argv 数组，无 shell）；`pi.ts` / `opencode.ts` / `mcp.ts` 各自只做 Runtime 接线。activation 是各 Adapter 内存中的 session 局部状态：不持久化、不跨 session 恢复。
 
-## 范围与非目标（V1）
+## 范围与非目标
 
-Herdr Link 是同一 workspace 内的消息互操作层，不是 Agent 生命周期或任务管理系统。它不提供 agent 创建/调度/回收、模型选择、workflow/task/stage 状态、业务结果 schema/evidence/receipt/review、ACK/wait/poll/retry/pending-request 语义或可靠投递保证、持久队列或跨 session 持久化、跨机器传输、权限审批、离线投递、**跨 workspace 的 discovery/send/close**（属于官方 Herdr Skill / CLI 控制面），或 workspace/topology 管理。业务 payload 放入 `message` 字段；Link 不解释其语义。完整范围以 [`PROTOCOL.md` §9](./PROTOCOL.md#9-non-goals) 为准。
+Herdr Link 是同一 workspace 内的互操作层，不是业务调度器或任务管理系统。它只提供调用方明确选择的 configured/explicit Agent start execution primitive；不负责业务角色选择、pane 创建/规划、Agent 调度/回收、模型选择、workflow/task/stage 状态、业务结果 schema/evidence/receipt/review、ACK/wait/poll/retry/pending-request 语义或可靠投递保证、持久队列或跨 session 状态、跨机器传输、权限审批、离线投递、**跨 workspace 的 discovery/send/close**（属于官方 Herdr Skill / CLI 控制面），或 workspace/topology 管理。业务 payload 放入 `message` 字段；Link 不解释其语义。完整范围以 [`PROTOCOL.md` §9](./PROTOCOL.md#9-non-goals) 为准。
 
 ## 许可证