herdr-link 0.3.1 → 0.4.1

package/src/herdr.ts

@@ -1,5 +1,7 @@
 import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
 import { randomBytes } from "node:crypto";
+import { resolve } from "node:path";
 import {
   AGENT_ERROR_DETAILS,
   buildEnvelope,
@@ -12,6 +14,8 @@ import {
   type LinkErrorCode,
   type PeerDirectory,
   type PeerInfo,
+  type StartAgentInput,
+  type StartAgentReceipt,
 } from "./protocol.ts";
 
 export interface HerdrCommandOutput {
@@ -99,6 +103,233 @@ async function runFor(args: string[], failureCode: LinkErrorCode): Promise<unkno
   }
 }
 
+interface ValidatedStartVariant {
+  kind: string;
+  args: string[];
+}
+
+interface ConfiguredStartAgent {
+  strategy?: "round-robin";
+  variants: ValidatedStartVariant[];
+}
+
+const startCursors = new Map<string, number>();
+const startLocks = new Map<string, Promise<void>>();
+const START_CONFIG_PATH_PARTS = [".agents", "agent_config.json"] as const;
+const START_INPUT_KEYS = new Set(["name", "pane", "config_agent", "kind", "args"]);
+
+/** @internal Test seam only: clears process-local configured-start state. */
+export function resetStartStateForTests(): void {
+  startCursors.clear();
+  startLocks.clear();
+}
+
+function hasOwn(value: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function startInputError(detail: string): HerdrLinkError {
+  return new HerdrLinkError("START_INPUT_INVALID", detail);
+}
+
+function startConfigError(
+  code: "START_CONFIG_NOT_FOUND" | "START_AGENT_NOT_FOUND" | "START_CONFIG_INVALID",
+  detail: string,
+): HerdrLinkError {
+  return new HerdrLinkError(code, detail);
+}
+
+function validateStartInput(input: unknown):
+  | { mode: "configured"; name: string; pane: string; configAgent: string }
+  | { mode: "explicit"; name: string; pane: string; variant: ValidatedStartVariant } {
+  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: Record<string, unknown>, allowed: readonly string[], label: string): void {
+  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: unknown): Map<string, ConfiguredStartAgent> {
+  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 = new Map<string, ConfiguredStartAgent>();
+  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: ValidatedStartVariant[] = 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" as const } : {}),
+      variants,
+    });
+  }
+  return result;
+}
+
+async function loadConfiguredStartAgents(configPath: string): Promise<Map<string, ConfiguredStartAgent>> {
+  let text: string;
+  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: unknown;
+  try {
+    document = JSON.parse(text) as unknown;
+  } catch {
+    throw startConfigError("START_CONFIG_INVALID", "agent_config.json is not valid JSON");
+  }
+  return validateConfiguredDocument(document);
+}
+
+async function withStartCursorLock<T>(key: string, operation: () => Promise<T>): Promise<T> {
+  const previous = startLocks.get(key) ?? Promise.resolve();
+  let release!: () => void;
+  const current = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  startLocks.set(key, current);
+  await previous;
+  try {
+    return await operation();
+  } finally {
+    release();
+    if (startLocks.get(key) === current) startLocks.delete(key);
+  }
+}
+
+async function runStart(name: string, pane: string, variant: ValidatedStartVariant): Promise<void> {
+  try {
+    await runHerdr(["agent", "start", name, "--kind", variant.kind, "--pane", pane, "--", ...variant.args]);
+  } catch (error) {
+    // NOT_IN_HERDR is an environment/transport classification; all other
+    // Herdr start rejections belong to the start operation. This also
+    // prevents the shared agent_not_found mapping from becoming PEER_NOT_FOUND.
+    if (error instanceof HerdrLinkError && error.code === "NOT_IN_HERDR") throw error;
+    throw operationError(error, "START_FAILED");
+  }
+}
+
+export interface StartAgentOptions {
+  /** Runtime context directory used to locate the optional project config. */
+  cwd?: string;
+}
+
+/** Starts an Agent from a complete configured entry or a complete explicit launch specification. */
+export async function startAgent(input: StartAgentInput, options: StartAgentOptions = {}): Promise<StartAgentReceipt> {
+  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}\u0000${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 };
+  });
+}
+
 const CLI_ERROR_CODE_MAP: Record<string, LinkErrorCode> = {
   agent_not_found: "PEER_NOT_FOUND",
   not_in_herdr: "NOT_IN_HERDR",

package/src/mcp.ts

@@ -2,10 +2,10 @@
  * Shared stdio MCP server for Runtimes without a native custom-tool surface
  * (Claude Code, Codex, AGY) — ADR-013/ADR-014.
  *
- * Hand-written, line-delimited JSON-RPC 2.0 over stdin/stdout (zero
- * dependencies, no @modelcontextprotocol/sdk). Tool execution reuses the
- * herdr.ts control layer. Tool gating and error semantics follow
- * PROTOCOL.md §7; tool-name presentation follows PROTOCOL.md §4.4.
+ * Hand-written, line-delimited JSON-RPC 2.0 over stdin/stdout (no MCP SDK
+ * dependency). The published bundle uses only Node built-ins.
+ * Tool execution reuses the herdr.ts control layer. Tool gating and error semantics follow
+ * PROTOCOL.md §7; tool-name presentation follows PROTOCOL.md §4.6.
  *
  * Lazy presentation (blueprint v2): the tool surface is session-local and
  * dormant until activated. Outside Herdr, `tools/list` is empty. Inside
@@ -14,28 +14,32 @@
  * connection memory), emits `notifications/tools/list_changed`, and from
  * then on `tools/list` additionally offers the canonical Tier 1 tools.
  * Hosts that never refresh can keep dispatching through explicit gateway
- * actions (`{"action":"send","arguments":{...}}`). No daemon, no global
+ * actions (`{"action":"start","arguments":{...}}`). No daemon, no global
  * state: activation lives and dies with the connection.
  */
 import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 
-import { closeAgentPane, ensureSelfName, listPeers, sendMessage } from "./herdr.ts";
+import { closeAgentPane, ensureSelfName, listPeers, sendMessage, startAgent } from "./herdr.ts";
 import {
   COMMUNICATION_CONTRACT,
+  HERDR_LINK_COMMUNICATION_TOOLS,
   HERDR_LINK_GATEWAY,
   HERDR_LINK_TOOLS,
   HerdrLinkError,
+  START_TOOL_DESCRIPTION,
   TOOL_CLOSE,
   TOOL_PEERS,
   TOOL_SEND,
+  TOOL_START,
   formatAgentFacingError,
   type LinkErrorCode,
+  type StartAgentInput,
 } from "./protocol.ts";
 
 export const MCP_SERVER_NAME = "herdr-link";
 /** Keep in sync with package.json "version" (serverInfo is informational). */
-export const MCP_SERVER_VERSION = "0.2.1";
+export const MCP_SERVER_VERSION = "0.4.1";
 /** Fallback protocol version advertised when the client sends none. */
 export const MCP_PROTOCOL_VERSION = "2025-06-18";
 
@@ -47,7 +51,7 @@ export const TOOLS_LIST_CHANGED = "notifications/tools/list_changed";
 
 /**
  * JSON-RPC reserved error codes — transport/protocol-level failures only.
- * The five Link error codes (PROTOCOL.md §7) are never mapped onto these;
+ * The ten Link error codes (PROTOCOL.md §7) are never mapped onto these;
  * they travel inside CallToolResult as isError:true + "CODE: detail" text.
  */
 export const PARSE_ERROR = -32700;
@@ -70,10 +74,11 @@ export interface JsonRpcResponse {
  */
 export type NotificationSink = (notification: Record<string, unknown>) => void;
 
-type CanonicalToolName = typeof TOOL_PEERS | typeof TOOL_SEND | typeof TOOL_CLOSE;
+type CanonicalToolName = (typeof HERDR_LINK_TOOLS)[number];
 
 const NORMAL_MESSAGING_RULE = "Use Herdr Link, not raw Herdr CLI, pane ids, or terminal input, for normal inter-agent messaging.";
 const TOOL_DESCRIPTIONS: Record<CanonicalToolName, string> = {
+  [TOOL_START]: `${START_TOOL_DESCRIPTION} ${NORMAL_MESSAGING_RULE}`,
   [TOOL_PEERS]: `Discover live named peers in the same Herdr workspace; each state is advisory and Agent Names are the only addresses. ${NORMAL_MESSAGING_RULE}`,
   [TOOL_SEND]:
     `Send a herdr-link/1 message to a live named peer in your own workspace; status "sent" means Herdr accepted delivery. ${NORMAL_MESSAGING_RULE}`,
@@ -82,6 +87,21 @@ const TOOL_DESCRIPTIONS: Record<CanonicalToolName, string> = {
 };
 
 const TOOL_INPUT_SCHEMAS: Record<CanonicalToolName, Record<string, unknown>> = {
+  [TOOL_START]: {
+    type: "object",
+    properties: {
+      name: { type: "string", description: "New Herdr Agent Name" },
+      pane: { type: "string", description: "Existing pane id" },
+      config_agent: { type: "string", description: "Configured Agent key; do not combine with kind or args" },
+      kind: { type: "string", description: "Herdr Agent kind for explicit start" },
+      args: { type: "array", items: { type: "string" }, description: "Complete Herdr Agent arguments for explicit start" },
+    },
+    required: ["name", "pane"],
+    oneOf: [
+      { required: ["config_agent"], not: { anyOf: [{ required: ["kind"] }, { required: ["args"] }] } },
+      { required: ["kind", "args"], not: { required: ["config_agent"] } },
+    ],
+  },
   [TOOL_PEERS]: { type: "object", properties: {} },
   [TOOL_SEND]: {
     type: "object",
@@ -102,6 +122,7 @@ const TOOL_INPUT_SCHEMAS: Record<CanonicalToolName, Record<string, unknown>> = {
 
 /** Unexpected exceptions fall back to the operation's own failure code so the §7 vocabulary stays closed. */
 const FALLBACK_ERROR_CODE: Record<CanonicalToolName, LinkErrorCode> = {
+  [TOOL_START]: "START_FAILED",
   [TOOL_PEERS]: "NOT_IN_HERDR",
   [TOOL_SEND]: "SEND_FAILED",
   [TOOL_CLOSE]: "CLOSE_FAILED",
@@ -115,10 +136,9 @@ const FALLBACK_ERROR_CODE: Record<CanonicalToolName, LinkErrorCode> = {
 const GATEWAY_TOOL: { name: typeof HERDR_LINK_GATEWAY; description: string; inputSchema: Record<string, unknown> } = {
   name: HERDR_LINK_GATEWAY,
   description:
-    "Herdr Link gateway. Activate only when the user explicitly asks to use Herdr or when handling an inbound Herdr Link message. Cross-agent messaging starts dormant: call this tool once with no arguments " +
-    "({}) to activate it for this session — the host is notified via notifications/tools/list_changed " +
-    "and herdr_link_peers / herdr_link_send / herdr_link_close become available as regular tools. " +
-    'If your host did not refresh its tool list, keep dispatching through the gateway: {"action":"peers"}, ' +
+    "Herdr Link gateway. Activate only when the user explicitly asks to use Herdr or when handling an inbound Herdr Link message. Cross-agent control starts dormant: call this tool once with no arguments " +
+    "({}) to activate it for this session — the host is notified via notifications/tools/list_changed and herdr_link_start / herdr_link_peers / herdr_link_send / herdr_link_close become available as regular tools. " +
+    'If your host did not refresh its tool list, keep dispatching through the gateway: {"action":"start","arguments":{...}}, {"action":"peers"}, ' +
     '{"action":"send","arguments":{"to":...,"message":...}}, or ' +
     '{"action":"close","arguments":{"agent":...}}.',
   inputSchema: {
@@ -126,9 +146,9 @@ const GATEWAY_TOOL: { name: typeof HERDR_LINK_GATEWAY; description: string; inpu
     properties: {
       action: {
         type: "string",
-        enum: ["activate", "peers", "send", "close"],
+        enum: ["activate", "start", "peers", "send", "close"],
         description:
-          'Omit or use "activate" to turn the session on; other values dispatch the corresponding peers, send, or close capability.',
+          'Omit or use "activate" to turn the session on; other values dispatch the corresponding start, peers, send, or close capability.',
       },
       arguments: {
         type: "object",
@@ -230,6 +250,7 @@ export interface McpServerDeps {
   listPeers?: typeof listPeers;
   sendMessage?: typeof sendMessage;
   closeAgentPane?: typeof closeAgentPane;
+  startAgent?: typeof startAgent;
   /**
    * Receives server-to-host notifications (currently only
    * `notifications/tools/list_changed`). Defaults to stdout.
@@ -250,6 +271,7 @@ export function createRequestHandler(
   const runPeers = deps.listPeers ?? listPeers;
   const runSend = deps.sendMessage ?? sendMessage;
   const runClose = deps.closeAgentPane ?? closeAgentPane;
+  const runStart = deps.startAgent ?? startAgent;
   const notify = deps.notify ?? stdoutNotificationSink;
 
   /** Session-local lazy activation (blueprint v2). True ⇒ Tier 1 tools are listed. */
@@ -295,6 +317,8 @@ export function createRequestHandler(
     args: Record<string, unknown>,
   ): Promise<object> {
     switch (canonicalName) {
+      case TOOL_START:
+        return await runStart(args as unknown as StartAgentInput);
       case TOOL_PEERS:
         return await runPeers();
       case TOOL_SEND: {
@@ -338,22 +362,24 @@ export function createRequestHandler(
       activateSession();
       return callSuccess(id, {
         status: "active",
-        capabilities: ["peers", "send", "close"],
+        capabilities: ["start", "peers", "send", "close"],
       });
     }
     if (
       typeof action !== "string" ||
-      !(["peers", "send", "close"] as readonly string[]).includes(action)
+      !(["start", "peers", "send", "close"] as readonly string[]).includes(action)
     ) {
       return fail(id, INVALID_PARAMS, `Unknown gateway action: ${String(action)}`);
     }
     const canonicalName = (
-      action === "peers" ? TOOL_PEERS : action === "send" ? TOOL_SEND : TOOL_CLOSE
+      action === "start" ? TOOL_START : action === "peers" ? TOOL_PEERS : action === "send" ? TOOL_SEND : TOOL_CLOSE
     ) as CanonicalToolName;
     activateSession();
     // Prefer the nested canonical arguments object; otherwise accept the
     // remaining top-level fields directly (deterministic either way).
-    const dispatchArgs = isRecord(args.arguments) ? args.arguments : args;
+    const dispatchArgs = isRecord(args.arguments)
+      ? args.arguments
+      : Object.fromEntries(Object.entries(args).filter(([key]) => key !== "action"));
     return await callCanonicalTool(id, canonicalName, dispatchArgs);
   }
 
@@ -479,9 +505,8 @@ export async function runStdioServer(
 }
 
 /**
- * Host-facing presented name for a canonical tool on prefix-style hosts (PROTOCOL.md
- * §4.4): the full canonical name is always the suffix. The namespace is
- * host-specific ("herdr_link" for the Codex wiring) and deliberately NOT
+ * Host-facing presented name for a canonical tool on prefix-style hosts (PROTOCOL.md §4.6): the full canonical name is always the suffix. The namespace is
+ * host-specific (`herdr_link` for the Codex wiring) and deliberately NOT
  * defaulted — serverInfo.name and the host tool namespace are different
  * concerns, so callers must state explicitly which namespace a contract declares.
  */
@@ -504,15 +529,18 @@ function contractWithAppendix(appendix: string): string {
  * gateway is listed until the model activates it (blueprint v2).
  */
 export function buildMcpPrefixedCommunicationContract(namespace: string): string {
-  const [peers, send, close] = HERDR_LINK_TOOLS.map((name) =>
+  const [peers, send, close] = HERDR_LINK_COMMUNICATION_TOOLS.map((name) =>
     mcpPresentedToolName(name, namespace),
   );
+  const start = mcpPresentedToolName(TOOL_START, namespace);
   const gateway = mcpPresentedToolName(HERDR_LINK_GATEWAY, namespace);
   return contractWithAppendix(
     `In this runtime Herdr Link starts dormant: only the ${gateway} gateway tool is listed until it is activated.\n` +
       `- Call ${gateway} once with no arguments ({}); the host then receives notifications/tools/list_changed and the cross-agent tools become available.\n` +
-      `- If the host did not refresh its tool list, keep dispatching through the gateway: {"action":"peers"}, {"action":"send","arguments":{...}}, {"action":"close","arguments":{...}}.\n` +
+      `- 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":{...}}.\n` +
+      `- ${START_TOOL_DESCRIPTION}\n` +
       `The tools are presented under MCP-prefixed names (the canonical name is always the suffix):\n` +
+      `- herdr_link_start -> ${start}\n` +
       `- herdr_link_peers -> ${peers}\n` +
       `- herdr_link_send -> ${send}\n` +
       `- herdr_link_close -> ${close}`,
@@ -522,7 +550,7 @@ export function buildMcpPrefixedCommunicationContract(namespace: string): string
 /**
  * Contract text for wrapper-style MCP hosts (e.g. AGY's call_mcp_tool): the
  * model invokes one native wrapper carrying ServerName/ToolName/Arguments
- * instead of per-tool functions (PROTOCOL.md §4.4 wrapper form). Both values
+ * instead of per-tool functions (PROTOCOL.md §4.6 wrapper form). Both values
  * must be explicit. Presentation is lazy (blueprint v2): activate the gateway
  * first, then address the canonical tools through the same wrapper.
  */
@@ -533,11 +561,12 @@ export function buildMcpWrapperCommunicationContract(
   return contractWithAppendix(
     `In this runtime Herdr Link starts dormant: only the Tier 0 gateway (${HERDR_LINK_GATEWAY}) is listed until it is activated.\n` +
       `- Invoke the gateway once with empty Arguments {} (ToolName "${HERDR_LINK_GATEWAY}"); the host then receives notifications/tools/list_changed and the cross-agent tools become available.\n` +
-      `- If the host did not refresh its tool list, keep dispatching through the gateway with ToolName "${HERDR_LINK_GATEWAY}" and an Arguments object carrying {"action":"peers"|"send"|"close", ...}.\n\n` +
+      `- If the host did not refresh its tool list, keep dispatching through the gateway with ToolName "${HERDR_LINK_GATEWAY}" and an Arguments object carrying {"action":"start"|"peers"|"send"|"close", ...}.\n` +
+      `- ${START_TOOL_DESCRIPTION}\n\n` +
       `After activation, Herdr Link MCP tools are invoked through ${wrapperName}.\n\n` +
       `Use:\n` +
       `- ServerName: "${serverName}"\n` +
-      `- ToolName: "herdr_link_peers", "herdr_link_send", or "herdr_link_close"\n` +
+      `- ToolName: "herdr_link_start", "herdr_link_peers", "herdr_link_send", or "herdr_link_close"\n` +
       `- Arguments: the canonical input object for that Herdr Link tool`,
   );
 }

package/src/opencode.ts

@@ -4,11 +4,11 @@
  * The model-facing surface is exactly one tiny `herdr_link` dispatcher tool,
  * in both dormant and active states. Calling it with no arguments (`{}`)
  * idempotently activates the channel for the CURRENT session and returns
- * `{ status: "active", capabilities: ["peers", "send", "close"] }`; while a
+ * `{ status: "active", capabilities: ["start", "peers", "send", "close"] }`; while a
  * session is active the same gateway executes deterministic actions
- * (`action`: "peers" | "send" | "close") against the core control layer and
+ * (`action`: "start" | "peers" | "send" | "close") against the core control layer and
  * the compact Communication Contract is injected into that session's system
- * prompt. The three Tier 1 tools are never registered as always-resident
+ * prompt. The Tier 1 capabilities are never registered as always-resident
  * surfaces.
  *
  * API basis (public @opencode-ai/plugin 1.18.x only):
@@ -30,17 +30,20 @@
  */
 import { tool, type Plugin } from "@opencode-ai/plugin";
 
-import { closeAgentPane, ensureSelfName, listPeers, sendMessage } from "./herdr.ts";
+import { closeAgentPane, ensureSelfName, listPeers, sendMessage, startAgent } from "./herdr.ts";
 import {
   COMMUNICATION_CONTRACT,
   HERDR_LINK_GATEWAY,
   HerdrLinkError,
+  START_TOOL_DESCRIPTION,
   formatAgentFacingError,
   type LinkErrorCode,
+  type StartAgentInput,
 } from "./protocol.ts";
 
 /** Runtime-specific active presentation; the semantic Contract remains canonical. */
 const 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.`;
@@ -67,7 +70,7 @@ function failWith(error: unknown, fallbackCode: LinkErrorCode): never {
 /** Dispatcher-level usage guard for actions rejected by the schema anyway. */
 function failInvalidAction(action: string): never {
   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.`,
   );
 }
 
@@ -90,16 +93,16 @@ export const herdrLinkPlugin: Plugin = async () => {
     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. " +
+          "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 "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 — ' +
-            'only after any final send has returned status "sent", and in a later tool step.',
+            '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 — ' +
+            '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"])
+            .enum(["start", "peers", "send", "close"])
             .optional()
             .describe(
-              'Operation to run: "peers" | "send" | "close". Omit action entirely (call with {}) to activate Herdr Link for this session.',
+              'Operation to run: "start", "peers", "send", or "close". Omit action entirely (call with {}) to activate Herdr Link for this session.',
             ),
           to: tool.schema
             .string()
@@ -113,16 +116,45 @@ export const herdrLinkPlugin: Plugin = async () => {
             .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 === undefined) {
             activatedSessions.add(context.sessionID);
-            return jsonResult({ status: "active", capabilities: ["peers", "send", "close"] });
+            return jsonResult({ status: "active", capabilities: ["start", "peers", "send", "close"] });
           }
           // Gateway action dispatch is also an explicit activation path for
           // hosts that bypass the empty gateway call or do not refresh schemas.
           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 as unknown as StartAgentInput, { cwd: context.directory }));
+            } catch (error) {
+              failWith(error, "START_FAILED");
+            }
+          }
+
           if (args.action === "peers") {
             try {
               return jsonResult(await listPeers());