herdr-link 0.3.1 → 0.4.1

package/dist/herdr-link.opencode.js

@@ -3,7 +3,9 @@ import { tool } from "@opencode-ai/plugin";
 
 // src/herdr.ts
 import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
 import { randomBytes } from "node:crypto";
+import { resolve } from "node:path";
 
 // src/protocol.ts
 var PROTOCOL_ID = "herdr-link/1";
@@ -19,6 +21,7 @@ function toAgentState(value) {
   }
   return "unknown";
 }
+var START_TOOL_DESCRIPTION = "Start a new Herdr Agent in an existing pane. Provide name and pane, then choose exactly one complete parameter source: config_agent for .agents/agent_config.json, or kind plus args for explicit Herdr start parameters. These modes are mutually exclusive; partial overrides are not supported. This operation does not create panes or retry/fallback after failure.";
 var HerdrLinkError = class extends Error {
   code;
   constructor(code, detail) {
@@ -32,7 +35,12 @@ var AGENT_ERROR_DETAILS = {
   SELF_UNNAMED: "Herdr Link could not establish a stable Agent Name",
   PEER_NOT_FOUND: "target agent is not a live peer",
   SEND_FAILED: "Herdr did not accept message delivery",
-  CLOSE_FAILED: "Herdr pane close failed"
+  CLOSE_FAILED: "Herdr pane close failed",
+  START_CONFIG_NOT_FOUND: "configured Agent start configuration was not found",
+  START_AGENT_NOT_FOUND: "configured Agent start entry was not found",
+  START_CONFIG_INVALID: "configured Agent start configuration is invalid",
+  START_INPUT_INVALID: "Agent start input is invalid",
+  START_FAILED: "Herdr did not accept Agent start"
 };
 function formatAgentFacingError(error, fallbackCode) {
   const code = error instanceof HerdrLinkError ? error.code : fallbackCode;
@@ -104,14 +112,14 @@ var COMMUNICATION_CONTRACT = `Herdr Link is the standard interoperability channe
 function attachCliOutput(error, stdout, stderr) {
   Object.assign(error, { stdout, stderr });
 }
-var defaultHerdrRunner = (file, args) => new Promise((resolve, reject) => {
+var defaultHerdrRunner = (file, args) => new Promise((resolve2, reject) => {
   execFile(file, args, { encoding: "utf8", shell: false }, (error, stdout, stderr) => {
     if (error) {
       attachCliOutput(error, String(stdout), String(stderr));
       reject(error);
       return;
     }
-    resolve({ stdout: String(stdout), stderr: String(stderr) });
+    resolve2({ stdout: String(stdout), stderr: String(stderr) });
   });
 });
 var herdrRunner = defaultHerdrRunner;
@@ -160,6 +168,180 @@ async function runFor(args, failureCode) {
     throw operationError(error, failureCode);
   }
 }
+var startCursors = /* @__PURE__ */ new Map();
+var startLocks = /* @__PURE__ */ new Map();
+var START_CONFIG_PATH_PARTS = [".agents", "agent_config.json"];
+var START_INPUT_KEYS = /* @__PURE__ */ new Set(["name", "pane", "config_agent", "kind", "args"]);
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+function startInputError(detail) {
+  return new HerdrLinkError("START_INPUT_INVALID", detail);
+}
+function startConfigError(code, detail) {
+  return new HerdrLinkError(code, detail);
+}
+function validateStartInput(input) {
+  const value = asRecord(input);
+  if (!value) throw startInputError("start input must be an object");
+  for (const key of Object.keys(value)) {
+    if (!START_INPUT_KEYS.has(key)) throw startInputError(`unknown start field "${key}"`);
+  }
+  const name = value.name;
+  if (typeof name !== "string" || !isValidAgentName(name)) {
+    throw startInputError('"name" must be a valid Herdr Agent Name');
+  }
+  const pane = value.pane;
+  if (typeof pane !== "string" || pane.trim() === "") {
+    throw startInputError('"pane" must be a non-empty pane id');
+  }
+  const hasConfigAgent = hasOwn(value, "config_agent");
+  const hasKind = hasOwn(value, "kind");
+  const hasArgs = hasOwn(value, "args");
+  if (hasConfigAgent && (hasKind || hasArgs)) {
+    throw startInputError("config_agent cannot be combined with kind or args");
+  }
+  if (hasConfigAgent) {
+    const configAgent = value.config_agent;
+    if (typeof configAgent !== "string" || configAgent.trim() === "") {
+      throw startInputError('"config_agent" must be a non-empty string');
+    }
+    return { mode: "configured", name, pane, configAgent };
+  }
+  if (!hasKind || !hasArgs) {
+    throw startInputError("explicit start requires both kind and args");
+  }
+  const kind = value.kind;
+  if (typeof kind !== "string" || kind.trim() === "") {
+    throw startInputError('"kind" must be a non-empty string');
+  }
+  const args = value.args;
+  if (!Array.isArray(args) || !args.every((arg) => typeof arg === "string")) {
+    throw startInputError('"args" must be an array of strings');
+  }
+  return { mode: "explicit", name, pane, variant: { kind, args: [...args] } };
+}
+function assertAllowedKeys(value, allowed, label) {
+  const allowedSet = new Set(allowed);
+  for (const key of Object.keys(value)) {
+    if (!allowedSet.has(key)) throw startConfigError("START_CONFIG_INVALID", `${label} contains unknown field "${key}"`);
+  }
+}
+function validateConfiguredDocument(document) {
+  const root = asRecord(document);
+  if (!root) throw startConfigError("START_CONFIG_INVALID", "configuration root must be an object");
+  assertAllowedKeys(root, ["version", "agents"], "configuration root");
+  if (root.version !== 1) throw startConfigError("START_CONFIG_INVALID", "configuration version must be 1");
+  const agents = asRecord(root.agents);
+  if (!agents) throw startConfigError("START_CONFIG_INVALID", "agents must be an object");
+  const result = /* @__PURE__ */ new Map();
+  for (const [configAgent, rawEntry] of Object.entries(agents)) {
+    if (configAgent.trim() === "") {
+      throw startConfigError("START_CONFIG_INVALID", "agents contains an empty configuration key");
+    }
+    const entry = asRecord(rawEntry);
+    if (!entry) throw startConfigError("START_CONFIG_INVALID", `agents.${configAgent} must be an object`);
+    assertAllowedKeys(entry, ["strategy", "variants"], `agents.${configAgent}`);
+    const rawVariants = entry.variants;
+    if (!Array.isArray(rawVariants) || rawVariants.length === 0) {
+      throw startConfigError("START_CONFIG_INVALID", `agents.${configAgent}.variants must be non-empty`);
+    }
+    const hasStrategy = hasOwn(entry, "strategy");
+    if (hasStrategy && entry.strategy !== "round-robin") {
+      throw startConfigError("START_CONFIG_INVALID", `agents.${configAgent}.strategy is unsupported`);
+    }
+    if (rawVariants.length > 1 && entry.strategy !== "round-robin") {
+      throw startConfigError("START_CONFIG_INVALID", `agents.${configAgent} requires strategy round-robin for multiple variants`);
+    }
+    const variants = rawVariants.map((rawVariant, index) => {
+      const variant = asRecord(rawVariant);
+      if (!variant) throw startConfigError("START_CONFIG_INVALID", `agents.${configAgent}.variants[${index}] must be an object`);
+      assertAllowedKeys(variant, ["kind", "args"], `agents.${configAgent}.variants[${index}]`);
+      const kind = variant.kind;
+      if (typeof kind !== "string" || kind.trim() === "") {
+        throw startConfigError("START_CONFIG_INVALID", `agents.${configAgent}.variants[${index}].kind must be non-empty`);
+      }
+      const args = variant.args;
+      if (hasOwn(variant, "args") && (!Array.isArray(args) || !args.every((arg) => typeof arg === "string"))) {
+        throw startConfigError("START_CONFIG_INVALID", `agents.${configAgent}.variants[${index}].args must be an array of strings`);
+      }
+      return { kind, args: Array.isArray(args) ? [...args] : [] };
+    });
+    result.set(configAgent, {
+      ...hasStrategy ? { strategy: "round-robin" } : {},
+      variants
+    });
+  }
+  return result;
+}
+async function loadConfiguredStartAgents(configPath) {
+  let text;
+  try {
+    text = await readFile(configPath, "utf8");
+  } catch (error) {
+    const code = asRecord(error)?.code;
+    if (code === "ENOENT") {
+      throw startConfigError("START_CONFIG_NOT_FOUND", "agent_config.json was not found");
+    }
+    throw startConfigError("START_CONFIG_INVALID", "agent_config.json could not be read");
+  }
+  let document;
+  try {
+    document = JSON.parse(text);
+  } catch {
+    throw startConfigError("START_CONFIG_INVALID", "agent_config.json is not valid JSON");
+  }
+  return validateConfiguredDocument(document);
+}
+async function withStartCursorLock(key, operation) {
+  const previous = startLocks.get(key) ?? Promise.resolve();
+  let release;
+  const current = new Promise((resolve2) => {
+    release = resolve2;
+  });
+  startLocks.set(key, current);
+  await previous;
+  try {
+    return await operation();
+  } finally {
+    release();
+    if (startLocks.get(key) === current) startLocks.delete(key);
+  }
+}
+async function runStart(name, pane, variant) {
+  try {
+    await runHerdr(["agent", "start", name, "--kind", variant.kind, "--pane", pane, "--", ...variant.args]);
+  } catch (error) {
+    if (error instanceof HerdrLinkError && error.code === "NOT_IN_HERDR") throw error;
+    throw operationError(error, "START_FAILED");
+  }
+}
+async function startAgent(input, options = {}) {
+  assertHerdrEnvironment();
+  const validated = validateStartInput(input);
+  if (validated.mode === "explicit") {
+    await runStart(validated.name, validated.pane, validated.variant);
+    return { status: "started", agent: validated.name, kind: validated.variant.kind };
+  }
+  const projectRoot = typeof options.cwd === "string" && options.cwd.trim() !== "" ? options.cwd : process.cwd();
+  const configPath = resolve(projectRoot, ...START_CONFIG_PATH_PARTS);
+  const cursorKey = `${configPath}\0${validated.configAgent}`;
+  return withStartCursorLock(cursorKey, async () => {
+    const configuredAgents = await loadConfiguredStartAgents(configPath);
+    const configured = configuredAgents.get(validated.configAgent);
+    if (!configured) {
+      throw startConfigError("START_AGENT_NOT_FOUND", `configured Agent "${validated.configAgent}" was not found`);
+    }
+    const current = startCursors.get(cursorKey) ?? 0;
+    const variantIndex = current % configured.variants.length;
+    const variant = configured.variants[variantIndex];
+    await runStart(validated.name, validated.pane, variant);
+    if (configured.variants.length > 1) {
+      startCursors.set(cursorKey, (variantIndex + 1) % configured.variants.length);
+    }
+    return { status: "started", agent: validated.name, kind: variant.kind };
+  });
+}
 var CLI_ERROR_CODE_MAP = {
   agent_not_found: "PEER_NOT_FOUND",
   not_in_herdr: "NOT_IN_HERDR"
@@ -259,7 +441,7 @@ function stableName(record) {
 }
 var SELF_PROBE_ATTEMPTS = 3;
 var SELF_PROBE_DELAY_MS = 100;
-var sleepMs = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var sleepMs = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
 async function fetchSelfRecord(pane) {
   for (let attempt = 1; ; attempt += 1) {
     try {
@@ -422,6 +604,7 @@ async function closeAgentPane(agentName) {
 
 // src/opencode.ts
 var GATEWAY_PRESENTATION_APPENDIX = `In this runtime the active Herdr Link capabilities are dispatched through the single herdr_link gateway.
+- Use herdr_link with action "start": ${START_TOOL_DESCRIPTION}
 - Use herdr_link with action "peers" to list live same-workspace agents.
 - Use herdr_link with action "send" with to and message to deliver an inter-agent message or ordinary reply.
 - Use herdr_link with action "close" and an Agent Name only after any final send returns status "sent", in a later tool step.`;
@@ -439,7 +622,7 @@ function failWith(error, fallbackCode) {
 }
 function failInvalidAction(action) {
   throw new Error(
-    `INVALID_ACTION: herdr_link action "${action}" is not supported; use "peers", "send", "close", or omit action (call with {}) to activate.`
+    `INVALID_ACTION: herdr_link action "${action}" is not supported; use "start", "peers", "send", "close", or omit action (call with {}) to activate.`
   );
 }
 var herdrLinkPlugin = async () => {
@@ -452,21 +635,34 @@ var herdrLinkPlugin = async () => {
   return {
     tool: {
       [HERDR_LINK_GATEWAY]: tool({
-        description: `Herdr Link cross-agent communication gateway (herdr-link/1). Activate only when the user explicitly asks to use Herdr or when handling an inbound Herdr Link message. Call once with no arguments {} to activate Herdr Link for this session; the response lists capabilities. Then pass action "peers" to list live same-workspace agents, "send" with to + message to deliver an inter-agent message or ordinary reply, or "close" with agent to close a named agent's pane \u2014 only after any final send has returned status "sent", and in a later tool step.`,
+        description: `Herdr Link cross-agent control gateway (herdr-link/1). Activate only when the user explicitly asks to use Herdr or when handling an inbound Herdr Link message. Call once with no arguments {} to activate Herdr Link for this session; the response lists capabilities. Then pass action "start" with name + pane and either config_agent or complete kind + args, action "peers" to list live same-workspace agents, action "send" with to + message to deliver an inter-agent message or ordinary reply, or action "close" with agent to close a named agent's pane \u2014 start modes are mutually exclusive and close is only after any final send has returned status "sent", in a later tool step.`,
         args: {
-          action: tool.schema.enum(["peers", "send", "close"]).optional().describe(
-            'Operation to run: "peers" | "send" | "close". Omit action entirely (call with {}) to activate Herdr Link for this session.'
+          action: tool.schema.enum(["start", "peers", "send", "close"]).optional().describe(
+            'Operation to run: "start", "peers", "send", or "close". Omit action entirely (call with {}) to activate Herdr Link for this session.'
           ),
           to: tool.schema.string().optional().describe('Target agent name; required for action "send".'),
           message: tool.schema.string().optional().describe('Message payload; required for action "send".'),
-          agent: tool.schema.string().optional().describe('Target agent name; required for action "close".')
+          agent: tool.schema.string().optional().describe('Target agent name; required for action "close".'),
+          name: tool.schema.string().optional().describe('New Agent Name; required for action "start".'),
+          pane: tool.schema.string().optional().describe('Existing pane id; required for action "start".'),
+          config_agent: tool.schema.string().optional().describe('Configured Agent key for action "start"; do not combine with kind or args.'),
+          kind: tool.schema.string().optional().describe('Herdr Agent kind for explicit action "start".'),
+          args: tool.schema.array(tool.schema.string()).optional().describe('Complete Herdr Agent arguments for explicit action "start".')
         },
         async execute(args, context) {
           if (args.action === void 0) {
             activatedSessions.add(context.sessionID);
-            return jsonResult({ status: "active", capabilities: ["peers", "send", "close"] });
+            return jsonResult({ status: "active", capabilities: ["start", "peers", "send", "close"] });
           }
           activatedSessions.add(context.sessionID);
+          if (args.action === "start") {
+            const startInput = Object.fromEntries(Object.entries(args).filter(([key]) => key !== "action"));
+            try {
+              return jsonResult(await startAgent(startInput, { cwd: context.directory }));
+            } catch (error) {
+              failWith(error, "START_FAILED");
+            }
+          }
           if (args.action === "peers") {
             try {
               return jsonResult(await listPeers());

package/docs/mcp-wiring.md

@@ -1,22 +1,22 @@
 # MCP Adapter 接线指南（Claude Code / Codex / AGY）
 
-适用对象：没有原生自定义工具注册面的 Runtime（Claude Code、Codex、AGY）。三者共用同一个零依赖 stdio MCP server（决策见蓝图 ADR-013/ADR-014）；契约注入不经 MCP 通道，按 Runtime 分治。
+适用对象：没有原生自定义工具注册面的 Runtime（Claude Code、Codex、AGY）。三者共用同一个 stdio MCP server（不依赖 MCP SDK，配置使用 Node 原生 `JSON.parse`）；契约注入不经 MCP 通道，按 Runtime 分治。
 
 ## 形态总览
 
 ```text
 dist/herdr-link.mcp.js   单文件 bundle（esbuild 产出，行分隔 JSON-RPC over stdio）
-能力面                    Tier 0 gateway herdr_link + Tier 1 herdr_link_peers / herdr_link_send / herdr_link_close（canonical 名）
+能力面                    Tier 0 gateway herdr_link + Tier 1 herdr_link_start / herdr_link_peers / herdr_link_send / herdr_link_close（canonical 名）
 lazy 呈现                非 Herdr：tools/list = []
                          Herdr dormant：tools/list = [herdr_link]
                          激活（tools/call herdr_link {}）后：发射一次 notifications/tools/list_changed，
-                         本连接内 tools/list = [herdr_link, peers, send, close]；activation 随 stdio 连接存亡
+                         本连接内 tools/list = [herdr_link, start, peers, send, close]；activation 随 stdio 连接存亡
 listChanged fallback     不响应刷新的 Host 继续用 gateway 显式 action 分发：
-                         {"action":"peers"} / {"action":"send","arguments":{...}} /
+                         {"action":"start","arguments":{...}} / {"action":"peers"} / {"action":"send","arguments":{...}} /
                          {"action":"close","arguments":{...}}
 呈现方式                  Claude Code / Codex = mcp__herdr_link__<tool>
                          AGY   = call_mcp_tool(ServerName/ToolName/Arguments)
-错误语义                  五个 Link error 一律 isError:true + "CODE: detail" 文本（PROTOCOL §7）；
+错误语义                  十个 Link error 一律 isError:true + "CODE: detail" 文本（PROTOCOL §7）；
                          环境/transport 失败归类 NOT_IN_HERDR 且不被重包装
 零副作用                  非 Herdr 环境 tools/list 返回 []，模型无感知；stale host 注册表直接调用也返回 NOT_IN_HERDR
 契约/提示注入            dormant 启动只允许短 Tier-0 hint：
@@ -42,7 +42,7 @@ BUNDLE=$(pwd)/dist/herdr-link.mcp.js   # 后文统一引用
 
 运行只依赖 Node ≥ 22.6。server 由各 Runtime 在 Herdr managed pane 内拉起；**`HERDR_*` 环境变量是否透传给 MCP 子进程由各 Runtime 决定**——Codex 必须显式 `env_vars` 转发（§3），AGY 实测原生透传（§4），其余 Runtime 接入时先实测。
 
-**命名约束**：三家 Runtime 的 host registration namespace 均使用 `herdr_link`（下划线；连字符名在 Codex code-mode 工具面有兼容性问题）。Claude Code / Codex 以 prefix 形式呈现、AGY 以 wrapper 形式呈现（PROTOCOL §4.5），契约附录分别由 `buildMcpPrefixedCommunicationContract("herdr_link")` 与 `buildMcpWrapperCommunicationContract("call_mcp_tool", "herdr_link")` 生成（见 §1.2 / §1.3）。
+**命名约束**：三家 Runtime 的 host registration namespace 均使用 `herdr_link`（下划线；连字符名在 Codex code-mode 工具面有兼容性问题）。Claude Code / Codex 以 prefix 形式呈现、AGY 以 wrapper 形式呈现（PROTOCOL §4.6），契约附录分别由 `buildMcpPrefixedCommunicationContract("herdr_link")` 与 `buildMcpWrapperCommunicationContract("call_mcp_tool", "herdr_link")` 生成（见 §1.2 / §1.3）。
 
 ## 1. Active-state Contract 文本（canonical compact 共享 + Runtime presentation 附录）
 
@@ -73,8 +73,10 @@ Herdr Link is the standard interoperability channel between agents running in th
 ```text
 In this runtime Herdr Link starts dormant: only the mcp__herdr_link__herdr_link gateway tool is listed until it is activated.
 - Call mcp__herdr_link__herdr_link once with no arguments ({}); the host then receives notifications/tools/list_changed and the cross-agent tools become available.
-- If the host did not refresh its tool list, keep dispatching through the gateway: {"action":"peers"}, {"action":"send","arguments":{...}}, {"action":"close","arguments":{...}}.
+- If the host did not refresh its tool list, keep dispatching through the gateway: {"action":"start","arguments":{...}}, {"action":"peers"}, {"action":"send","arguments":{...}}, {"action":"close","arguments":{...}}.
+- Start a new Herdr Agent in an existing pane. Provide name and pane, then choose exactly one complete parameter source: config_agent for .agents/agent_config.json, or kind plus args for explicit Herdr start parameters. These modes are mutually exclusive; partial overrides are not supported. This operation does not create panes or retry/fallback after failure.
 The tools are presented under MCP-prefixed names (the canonical name is always the suffix):
+- herdr_link_start -> mcp__herdr_link__herdr_link_start
 - herdr_link_peers -> mcp__herdr_link__herdr_link_peers
 - herdr_link_send -> mcp__herdr_link__herdr_link_send
 - herdr_link_close -> mcp__herdr_link__herdr_link_close
@@ -87,13 +89,14 @@ AGY 的 model-facing 调用是单一原生 wrapper 携带 ServerName/ToolName/Ar
 ```text
 In this runtime Herdr Link starts dormant: only the Tier 0 gateway (herdr_link) is listed until it is activated.
 - Invoke the gateway once with empty Arguments {} (ToolName "herdr_link"); the host then receives notifications/tools/list_changed and the cross-agent tools become available.
-- If the host did not refresh its tool list, keep dispatching through the gateway with ToolName "herdr_link" and an Arguments object carrying {"action":"peers"|"send"|"close", ...}.
+- If the host did not refresh its tool list, keep dispatching through the gateway with ToolName "herdr_link" and an Arguments object carrying {"action":"start"|"peers"|"send"|"close", ...}.
+- Start a new Herdr Agent in an existing pane. Provide name and pane, then choose exactly one complete parameter source: config_agent for .agents/agent_config.json, or kind plus args for explicit Herdr start parameters. These modes are mutually exclusive; partial overrides are not supported. This operation does not create panes or retry/fallback after failure.
 
 After activation, Herdr Link MCP tools are invoked through call_mcp_tool.
 
 Use:
 - ServerName: "herdr_link"
-- ToolName: "herdr_link_peers", "herdr_link_send", or "herdr_link_close"
+- ToolName: "herdr_link_start", "herdr_link_peers", "herdr_link_send", or "herdr_link_close"
 - Arguments: the canonical input object for that Herdr Link tool
 ```
 
@@ -195,7 +198,7 @@ printf '%s\n' 'Herdr Link gateway: activate only when the user explicitly asks t
 }
 ```
 
-契约提示以 PreInvocation `ephemeralMessage` hook 为主通道：它只注入短 Tier-0 hint，不在 dormant 阶段生成完整 Contract。激活后由 wrapper 的 active tools/list descriptions 与 gateway dispatch 提供完整语义。实测注记（2026-08-23 transcript 取证）：AGY 的 model-facing MCP 调用是 **wrapper 形态**——`ServerName:"herdr_link"` + `ToolName` 参数化调用（非 `mcp__` 前缀独立函数），符合协议 §4.5 的 wrapper 条款。hooks 配置：
+契约提示以 PreInvocation `ephemeralMessage` hook 为主通道：它只注入短 Tier-0 hint，不在 dormant 阶段生成完整 Contract。激活后由 wrapper 的 active tools/list descriptions 与 gateway dispatch 提供完整语义。实测注记（2026-08-23 transcript 取证）：AGY 的 model-facing MCP 调用是 **wrapper 形态**——`ServerName:"herdr_link"` + `ToolName` 参数化调用（非 `mcp__` 前缀独立函数），符合协议 §4.6 的 wrapper 条款。hooks 配置：
 
 ```json
 {
@@ -252,15 +255,15 @@ printf '%s\n%s\n%s\n%s\n' \
   '{"jsonrpc":"2.0","id":4,"method":"tools/list"}' | node "$BUNDLE"
 ```
 
-预期：`initialize` 结果含 `"capabilities":{"tools":{"listChanged":true}}`；dormant list 仅 `herdr_link`；激活调用返回 `{"status":"active",...}` 且 stdout 在其后出现一行 `"method":"notifications/tools/list_changed"`；再次 `tools/list` 含 gateway + 三个 canonical 工具。对不存在的 peer 调用 `herdr_link_send`（或 gateway action 分发等价形式）应得到 `"isError":true` 且文本以 `PEER_NOT_FOUND:` 开头；跨 workspace 目标同样表现为 `PEER_NOT_FOUND`，不得泄漏目标存在于其他 workspace。
+预期：`initialize` 结果含 `"capabilities":{"tools":{"listChanged":true}}`；dormant list 仅 `herdr_link`；激活调用返回 `{"status":"active",...}` 且 stdout 在其后出现一行 `"method":"notifications/tools/list_changed"`；再次 `tools/list` 含 gateway + 四个 canonical 工具。对不存在的 peer 调用 `herdr_link_send`（或 gateway action 分发等价形式）应得到 `"isError":true` 且文本以 `PEER_NOT_FOUND:` 开头；跨 workspace 目标同样表现为 `PEER_NOT_FOUND`，不得泄漏目标存在于其他 workspace。
 
 ## 6. 行为边界（与 PROTOCOL.md 一致）
 
-- 工具失败是本地 tool failure：`NOT_IN_HERDR` / `SELF_UNNAMED` / `PEER_NOT_FOUND` / `SEND_FAILED` / `CLOSE_FAILED`，一律 `isError:true` 文本返回，进程不崩溃、不自动重试、不 fallback；
-- activation 是本 stdio 连接内的内存状态：连接断开即回到 dormant，不持久化、不跨连接共享；JSON-RPC 保留错误码（-32700 等）只用于 transport 层，五个 Link 错误码永不映射其上；
-- server 只调用 `agent get` / `agent list` / `agent prompt` / `pane close`，外加仅限 self identity bootstrap（PROTOCOL.md §6.3，目标只能是当前 pane 的未命名 occupant）的 `agent rename <self-pane>`，共五个 CLI 面，argv 数组执行，无 shell；每次通信调用实时解析 live identity/workspace 并强制 same-workspace guard；
+- 工具失败是本地 tool failure：`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`，一律 `isError:true` 文本返回，进程不崩溃、不自动重试、不 fallback；
+- activation 是本 stdio 连接内的内存状态：连接断开即回到 dormant，不持久化、不跨连接共享；JSON-RPC 保留错误码（-32700 等）只用于 transport 层，Link 错误码永不映射其上；
+- server 只调用 `agent get` / `agent list` / `agent prompt` / `agent start` / `pane close`，外加仅限 self identity bootstrap（PROTOCOL §6.3，目标只能是当前 pane 的未命名 occupant）的 `agent rename <self-pane>`，共六个 CLI 面，argv 数组执行，无 shell；每次通信调用实时解析 live identity/workspace 并强制 same-workspace guard；
 - server 启动时执行一次 `ensureSelfName()`（fire-and-forget，失败静默、稍后以 `SELF_UNNAMED` 呈现）：手动启动且未命名的 agent 无需人工 rename 即可成为可发现 peer；
-- 不提供 agent 创建/调度/回收、workspace/topology 控制等任何 Non-goals 能力；worker 生命周期仍由调用方决定；正常协作不依赖外部 `AGENTS.md` / Skill 补充 Contract。
+- 不提供业务调度、Agent 创建/回收、workspace/topology 控制等任何 Non-goals 能力；`herdr_link_start` 只执行调用方明确的 configured/explicit 启动选择；worker 生命周期其余部分仍由调用方决定；正常协作不依赖外部 `AGENTS.md` / Skill 补充 Contract。
 
 ## 7. 已知坑（Codex/AGY 真机实测）
 

package/examples/agent_config.example.json

@@ -0,0 +1,41 @@
+{
+  "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"
+          ]
+        }
+      ]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdr-link",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "pi": {
     "extensions": [
       "./src/pi.ts"
@@ -11,12 +11,13 @@
     "herdr",
     "agent-interop"
   ],
-  "description": "Herdr Link — cross-agent interoperability layer for Herdr sessions. V1: Pi / OpenCode native adapters + shared stdio MCP server for Claude Code / Codex / AGY.",
+  "description": "Herdr Link — cross-agent interoperability layer for Herdr sessions. Pi / OpenCode native adapters + shared stdio MCP server for Claude Code / Codex / AGY.",
   "files": [
     "PROTOCOL.md",
     "README.md",
     "CHANGELOG.md",
     "docs/mcp-wiring.md",
+    "examples/",
     "dist/",
     "src/",
     "scripts/mcp-probe.mjs"
@@ -40,7 +41,8 @@
     "typecheck": "tsc --noEmit",
     "test": "node --experimental-strip-types --test test/*.test.ts",
     "build:opencode": "esbuild src/opencode.ts --bundle --format=esm --platform=node --external:@opencode-ai/plugin --outfile=dist/herdr-link.opencode.js",
-    "build:mcp": "esbuild src/mcp.ts --bundle --format=esm --platform=node --target=node22 --banner:js='#!/usr/bin/env node' --outfile=dist/herdr-link.mcp.js"
+    "build:mcp": "esbuild src/mcp.ts --bundle --format=esm --platform=node --target=node22 --banner:js='#!/usr/bin/env node' --outfile=dist/herdr-link.mcp.js",
+    "check:mcp-bundle": "node scripts/check-mcp-bundle.mjs"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",