herdr-link 0.3.0 → 0.4.0

package/src/pi.ts

@@ -3,8 +3,8 @@
  *
  * Tier 0 (dormant): with the three Herdr environment variables present, the
  * adapter registers everything but keeps the model-facing surface down to the
- * tiny `herdr_link` gateway. The three Tier 1 tools
- * (`herdr_link_peers`/`herdr_link_send`/`herdr_link_close`) stay inactive and
+ * tiny `herdr_link` gateway. The four Tier 1 tools
+ * (`herdr_link_start`/`herdr_link_peers`/`herdr_link_send`/`herdr_link_close`) stay inactive and
  * no Communication Contract is injected.
  *
  * Tier 1 (active): calling the gateway with `{}` idempotently activates the
@@ -27,13 +27,27 @@
 import type { ExtensionAPI, ToolExecutionMode } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { closeAgentPane, ensureSelfName, listPeers, sendMessage } from "./herdr.ts";
-import { COMMUNICATION_CONTRACT, formatAgentFacingError } from "./protocol.ts";
-
-const TIER1_TOOL_NAMES = ["herdr_link_peers", "herdr_link_send", "herdr_link_close"] as const;
+import { closeAgentPane, ensureSelfName, listPeers, sendMessage, startAgent } from "./herdr.ts";
+import {
+  COMMUNICATION_CONTRACT,
+  HERDR_LINK_TOOLS,
+  START_TOOL_DESCRIPTION,
+  TOOL_START,
+  type StartAgentInput,
+  formatAgentFacingError,
+} from "./protocol.ts";
+
+const TIER1_TOOL_NAMES = HERDR_LINK_TOOLS;
 const TIER1_TOOL_SET = new Set<string>(TIER1_TOOL_NAMES);
 
 const GATEWAY_PARAMETERS = Type.Object({});
+const START_PARAMETERS = Type.Object({
+  name: Type.String(),
+  pane: Type.String(),
+  config_agent: Type.Optional(Type.String()),
+  kind: Type.Optional(Type.String()),
+  args: Type.Optional(Type.Array(Type.String())),
+});
 const PEERS_PARAMETERS = Type.Object({});
 const SEND_PARAMETERS = Type.Object({
   to: Type.String(),
@@ -51,7 +65,14 @@ function toolResult(value: object) {
   };
 }
 
-function rethrowToolError(error: unknown, fallbackCode: "NOT_IN_HERDR" | "SEND_FAILED" | "CLOSE_FAILED"): never {
+function rethrowToolError(
+  error: unknown,
+  fallbackCode:
+    | "NOT_IN_HERDR"
+    | "START_FAILED"
+    | "SEND_FAILED"
+    | "CLOSE_FAILED",
+): never {
   const toolError = new Error(formatAgentFacingError(error, fallbackCode), { cause: error });
   throw toolError;
 }
@@ -73,6 +94,20 @@ export default function (pi: ExtensionAPI): void {
   // setActiveTools), kept initially inactive by the session_start hook below.
   // Their descriptions alone carry the canonical affordances; prompt metadata
   // is intentionally omitted (see module doc).
+  pi.registerTool({
+    name: TOOL_START,
+    label: "Herdr Link Start",
+    description: START_TOOL_DESCRIPTION,
+    parameters: START_PARAMETERS,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      try {
+        return toolResult(await startAgent(params as StartAgentInput, { cwd: ctx.cwd }));
+      } catch (error) {
+        rethrowToolError(error, "START_FAILED");
+      }
+    },
+  });
+
   pi.registerTool({
     name: "herdr_link_peers",
     label: "Herdr Link Peers",
@@ -125,17 +160,17 @@ export default function (pi: ExtensionAPI): void {
   });
 
   // --- Tier 0 gateway: the only model-visible Herdr surface while dormant.
-  // It performs activation only; it never executes peers/send/close work.
+  // It performs activation only; it never executes start/peers/send/close work.
   pi.registerTool({
     name: "herdr_link",
     label: "Herdr Link",
     description:
-      "Activate the Herdr Link channel only when the user explicitly asks to use Herdr or when handling an inbound Herdr Link message. Call once with empty arguments {} before using Herdr Link; this enables herdr_link_peers, herdr_link_send, and herdr_link_close.",
-    promptSnippet: "Activate the Herdr Link cross-agent channel (peers/send/close).",
+      "Activate the Herdr Link channel only when the user explicitly asks to use Herdr or when handling an inbound Herdr Link message. Call once with empty arguments {} before using Herdr Link; this enables herdr_link_start, herdr_link_peers, herdr_link_send, and herdr_link_close.",
+    promptSnippet: "Activate the Herdr Link cross-agent channel (start/peers/send/close).",
     parameters: GATEWAY_PARAMETERS,
     async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
       activateChannel();
-      return toolResult({ status: "active", capabilities: ["peers", "send", "close"] });
+      return toolResult({ status: "active", capabilities: ["start", "peers", "send", "close"] });
     },
   });
 

package/src/protocol.ts

@@ -20,17 +20,19 @@ export const MESSAGE_ID_RE = /^hl_[a-z0-9]+_[a-z0-9]+$/;
  * docs/mcp-wiring.md). Tier 1 are the canonical tool names exposed
  * through the gateway. Both are stable machine-usable constants;
  * runtime-specific presented names must map deterministically onto them
- * (PROTOCOL.md §4.4).
+ * (PROTOCOL.md §4.6).
  * ------------------------------------------------------------------ */
 
 /** Tier 0 — gateway name in its underscore host-namespace form. */
 export const HERDR_LINK_GATEWAY = "herdr_link" as const;
 
 /** Tier 1 — canonical tool names exposed through the gateway. */
+export const TOOL_START = "herdr_link_start" as const;
 export const TOOL_PEERS = "herdr_link_peers" as const;
 export const TOOL_SEND = "herdr_link_send" as const;
 export const TOOL_CLOSE = "herdr_link_close" as const;
-export const HERDR_LINK_TOOLS = [TOOL_PEERS, TOOL_SEND, TOOL_CLOSE] as const;
+export const HERDR_LINK_TOOLS = [TOOL_START, TOOL_PEERS, TOOL_SEND, TOOL_CLOSE] as const;
+export const HERDR_LINK_COMMUNICATION_TOOLS = [TOOL_PEERS, TOOL_SEND, TOOL_CLOSE] as const;
 
 /* ------------------------------------------------------------------ *
  * Agent state (blueprint v2)
@@ -83,6 +85,41 @@ export interface AgentContext {
   agent_status: AgentState;
 }
 
+/** Common input for the Agent start execution primitive. */
+export interface StartCommonInput {
+  /** New Herdr Agent Name. */
+  name: string;
+  /** Existing pane in which Herdr starts the Agent. */
+  pane: string;
+}
+
+/** Project-configured start: the configuration owns the complete launch parameters. */
+export interface ConfiguredStartInput extends StartCommonInput {
+  config_agent: string;
+  kind?: never;
+  args?: never;
+}
+
+/** Explicit start: the caller owns the complete Herdr launch parameters. */
+export interface ExplicitStartInput extends StartCommonInput {
+  kind: string;
+  args: string[];
+  config_agent?: never;
+}
+
+export type StartAgentInput = ConfiguredStartInput | ExplicitStartInput;
+
+/** Stable receipt returned after Herdr accepts an Agent start. */
+export interface StartAgentReceipt {
+  status: "started";
+  agent: string;
+  kind: string;
+}
+
+/** Shared model-facing description; detailed config semantics live in the start section. */
+export const 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.";
+
 /** The cross-agent message envelope (PROTOCOL.md §2). Minimal fields only. */
 export interface HerdrLinkEnvelope {
   protocol: typeof PROTOCOL_ID;
@@ -99,6 +136,11 @@ export const LINK_ERROR_CODES = [
   "PEER_NOT_FOUND",
   "SEND_FAILED",
   "CLOSE_FAILED",
+  "START_CONFIG_NOT_FOUND",
+  "START_AGENT_NOT_FOUND",
+  "START_CONFIG_INVALID",
+  "START_INPUT_INVALID",
+  "START_FAILED",
 ] as const;
 
 export type LinkErrorCode = (typeof LINK_ERROR_CODES)[number];
@@ -121,6 +163,11 @@ export const AGENT_ERROR_DETAILS: Record<LinkErrorCode, string> = {
   PEER_NOT_FOUND: "target agent is not a live peer",
   SEND_FAILED: "Herdr did not accept message delivery",
   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",
 };
 
 /** Formats a Link failure without exposing raw Herdr topology or CLI details. */
@@ -259,7 +306,7 @@ export function extractInboundEnvelope(text: string): HerdrLinkEnvelope | undefi
  */
 export const COMMUNICATION_CONTRACT = `Herdr Link is the standard interoperability channel between agents running in the same Herdr workspace.
 
-1. Use herdr_link_peers to discover agent addresses; it lists only live agents in your own workspace, each with an advisory activity state.
+1. Use herdr_link_peers only for agent-address discovery or explicit recovery. Its activity state is advisory and must not be used to wait for or infer task completion. When further progress depends on a peer reply, end the current turn and continue when that reply arrives as a new inbound herdr-link/1 message.
 2. Use herdr_link_send to send messages to another agent.
 3. A message with protocol "herdr-link/1" is an inter-agent message.
 4. Treat its "message" field as content sent by the agent named in "from".