herdr-link 0.2.0

package/src/opencode.ts

@@ -0,0 +1,180 @@
+/**
+ * Herdr Link OpenCode Runtime adapter v2 — single-gateway presentation.
+ *
+ * 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
+ * session is active the same gateway executes deterministic actions
+ * (`action`: "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
+ * surfaces.
+ *
+ * API basis (public @opencode-ai/plugin 1.18.x only):
+ * - `Hooks.tool` registers tools process-wide; there is no public per-session
+ *   registration or dynamic unload, hence the single-gateway fallback instead
+ *   of Pi-style `setActiveTools`.
+ * - `ToolContext.sessionID` attributes each gateway execution to its session;
+ *   the per-session ephemeral activation set lives in the plugin closure.
+ * - `experimental.chat.system.transform` input carries `sessionID?`; it is
+ *   OPTIONAL in the public types, so injection fails closed when it is absent
+ *   (an unattributable system build is never treated as active).
+ *
+ * Known sessionID limitations (explicit):
+ * - `Hooks.tool.definition` exposes only `toolID` (no sessionID), so mutating
+ *   tool schemas per session cannot be done safely; the gateway schema is
+ *   static and admits both `{}` (activate) and fully-formed actions.
+ * - The activation set is in-memory per plugin instance: restarting the
+ *   OpenCode server returns every session to dormant until it re-activates.
+ */
+import { tool, type Plugin } from "@opencode-ai/plugin";
+
+import { closeAgentPane, ensureSelfName, listPeers, sendMessage } from "./herdr.ts";
+import {
+  COMMUNICATION_CONTRACT,
+  HERDR_LINK_GATEWAY,
+  HerdrLinkError,
+  formatAgentFacingError,
+  type LinkErrorCode,
+} 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 "peers" to list live same-workspace agents.
+- Use herdr_link with action "send", to, message, and reply_to when replying.
+- Use herdr_link with action "close" and an Agent Name only after any final send returns status "sent", in a later tool step.`;
+
+const GATEWAY_CONTRACT = `${COMMUNICATION_CONTRACT}\n\n${GATEWAY_PRESENTATION_APPENDIX}`;
+
+function isHerdrEnvironment(): boolean {
+  return (
+    process.env.HERDR_ENV === "1" &&
+    Boolean(process.env.HERDR_BIN_PATH) &&
+    Boolean(process.env.HERDR_PANE_ID)
+  );
+}
+
+function jsonResult(value: object): string {
+  return JSON.stringify(value);
+}
+
+/** Throws the stable `${CODE}: ${detail}` Agent-facing message; causes stay internal. */
+function failWith(error: unknown, fallbackCode: LinkErrorCode): never {
+  throw new Error(formatAgentFacingError(error, fallbackCode), { cause: error });
+}
+
+/** 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.`,
+  );
+}
+
+export const herdrLinkPlugin: Plugin = async () => {
+  if (!isHerdrEnvironment()) {
+    return {};
+  }
+
+  // Self identity bootstrap (PROTOCOL.md §6.3): fire-and-forget so plugin
+  // startup never blocks or fails on Herdr IO; gateway actions fall back
+  // through getSelfContext(). Failures surface later as SELF_UNNAMED.
+  void ensureSelfName().catch(() => {});
+
+  // Per-runtime-session activation set. Ephemeral by design: in-memory only,
+  // scoped to this plugin instance, never persisted, never shared across
+  // instances. Losing it (server restart) merely returns sessions to dormant.
+  const activatedSessions = new Set<string>();
+
+  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 (plus reply_to when replying) to deliver an inter-agent message, 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.',
+        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.',
+            ),
+          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".'),
+          reply_to: tool.schema
+            .string()
+            .optional()
+            .describe('Message id being replied to; optional, only with action "send".'),
+          agent: tool.schema
+            .string()
+            .optional()
+            .describe('Target agent name; required for action "close".'),
+        },
+        async execute(args, context) {
+          if (args.action === undefined) {
+            activatedSessions.add(context.sessionID);
+            return jsonResult({ status: "active", capabilities: ["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 === "peers") {
+            try {
+              return jsonResult(await listPeers());
+            } catch (error) {
+              failWith(error, "NOT_IN_HERDR");
+            }
+          }
+
+          if (args.action === "send") {
+            if (typeof args.to !== "string" || args.to === "") {
+              failWith(new HerdrLinkError("SEND_FAILED", '"to" must be a non-empty string'), "SEND_FAILED");
+            }
+            if (typeof args.message !== "string" || args.message === "") {
+              failWith(new HerdrLinkError("SEND_FAILED", '"message" must be a non-empty string'), "SEND_FAILED");
+            }
+            try {
+              const envelope = await sendMessage(args.to, args.message, args.reply_to);
+              return jsonResult({ status: "sent", id: envelope.id, to: envelope.to });
+            } catch (error) {
+              failWith(error, "SEND_FAILED");
+            }
+          }
+
+          if (args.action === "close") {
+            if (typeof args.agent !== "string" || args.agent === "") {
+              failWith(new HerdrLinkError("CLOSE_FAILED", '"agent" must be a non-empty string'), "CLOSE_FAILED");
+            }
+            try {
+              await closeAgentPane(args.agent);
+              return jsonResult({ status: "closed", agent: args.agent });
+            } catch (error) {
+              failWith(error, "CLOSE_FAILED");
+            }
+          }
+
+          failInvalidAction(String(args.action));
+        },
+      }),
+    },
+    "experimental.chat.system.transform": async (input, output) => {
+      // Fail closed: an optional/absent sessionID cannot be attributed to an
+      // activation, so the Contract is withheld rather than guessed.
+      if (input.sessionID === undefined || !activatedSessions.has(input.sessionID)) {
+        return;
+      }
+      if (!output.system.includes(GATEWAY_CONTRACT)) {
+        output.system.push(GATEWAY_CONTRACT);
+      }
+    },
+  };
+};

package/src/pi.ts

@@ -0,0 +1,170 @@
+/**
+ * Herdr Link Pi Runtime adapter v2 — Tier 0/Tier 1 presentation.
+ *
+ * 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
+ * no Communication Contract is injected.
+ *
+ * Tier 1 (active): calling the gateway with `{}` idempotently activates the
+ * channel inside the current runtime session via the official dynamic tool
+ * API (`pi.setActiveTools`, additive change) and starts injecting the compact
+ * Contract through `before_agent_start`.
+ *
+ * API basis (public Pi Extension API, @earendil-works/pi-coding-agent 0.84.x):
+ * - `pi.registerTool()` must cover every tool before it can appear in
+ *   `pi.setActiveTools()` ("Names passed to pi.setActiveTools() must already
+ *   be registered"); action methods throw while extensions are still loading,
+ *   so the initial dormant set is applied on `session_start` — the same
+ *   pattern as the official Dynamic Tool Loading example in docs/extensions.md.
+ * - Activation inside a tool `execute()` may call `pi.setActiveTools()`
+ *   additively; Pi applies the new set before the next model request.
+ * - Lazily loaded tools should omit active-only prompt metadata
+ *   (`promptSnippet`/`promptGuidelines`) and rely on their `description`;
+ *   activating such metadata would rebuild the system prompt mid-session.
+ */
+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;
+const TIER1_TOOL_SET = new Set<string>(TIER1_TOOL_NAMES);
+
+const GATEWAY_PARAMETERS = Type.Object({});
+const PEERS_PARAMETERS = Type.Object({});
+const SEND_PARAMETERS = Type.Object({
+  to: Type.String(),
+  message: Type.String(),
+  reply_to: Type.Optional(Type.String()),
+});
+const CLOSE_PARAMETERS = Type.Object({
+  agent: Type.String(),
+});
+
+
+function toolResult(value: object) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(value) }],
+    details: value,
+  };
+}
+
+function rethrowToolError(error: unknown, fallbackCode: "NOT_IN_HERDR" | "SEND_FAILED" | "CLOSE_FAILED"): never {
+  const toolError = new Error(formatAgentFacingError(error, fallbackCode), { cause: error });
+  throw toolError;
+}
+
+export default function (pi: ExtensionAPI): void {
+  if (
+    process.env.HERDR_ENV !== "1" ||
+    !process.env.HERDR_BIN_PATH ||
+    !process.env.HERDR_PANE_ID
+  ) {
+    return;
+  }
+
+  // Per-runtime-session state only: never persisted, never shared across
+  // sessions. Every session start returns the channel to dormant.
+  let activated = false;
+
+  // --- Tier 1 tools: registered up front (Pi requires registration before
+  // 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: "herdr_link_peers",
+    label: "Herdr Link Peers",
+    description:
+      "Discover named agents available through the cross-agent communication channel. Returns { self, peers }; addresses are Agent Names.",
+    parameters: PEERS_PARAMETERS,
+    async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+      try {
+        return toolResult(await listPeers());
+      } catch (error) {
+        rethrowToolError(error, "NOT_IN_HERDR");
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "herdr_link_send",
+    label: "Herdr Link Send",
+    description:
+      'Send an inter-agent message (protocol herdr-link/1) to another agent through the cross-agent communication channel. status "sent" means Herdr accepted delivery, not that the peer finished its task. When replying, set reply_to to the received message id.',
+    parameters: SEND_PARAMETERS,
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      try {
+        const envelope = await sendMessage(params.to, params.message, params.reply_to);
+        return toolResult({ status: "sent", id: envelope.id, to: envelope.to });
+      } catch (error) {
+        rethrowToolError(error, "SEND_FAILED");
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "herdr_link_close",
+    label: "Herdr Link Close",
+    // Pi 默认并行执行同一 assistant response 的 sibling tool calls；close 与 send 同批时
+    // 必须保证 send 先完成（"sent" 语义=Herdr 已接受投递），故 close 声明为 sequential，
+    // 使含 close 的批次整体串行。peers/send 保持默认并行。
+    executionMode: "sequential" as ToolExecutionMode,
+    description:
+      'Close the Herdr pane currently hosting a named agent. Sequential: if a final message is needed, send it first and call close in a later tool step after herdr_link_send returns status "sent".',
+    parameters: CLOSE_PARAMETERS,
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      try {
+        await closeAgentPane(params.agent);
+        return toolResult({ status: "closed", agent: params.agent });
+      } catch (error) {
+        rethrowToolError(error, "CLOSE_FAILED");
+      }
+    },
+  });
+
+  // --- Tier 0 gateway: the only model-visible Herdr surface while dormant.
+  // It performs activation only; it never executes 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).",
+    parameters: GATEWAY_PARAMETERS,
+    async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+      activateChannel();
+      return toolResult({ status: "active", capabilities: ["peers", "send", "close"] });
+    },
+  });
+
+  // Additive-only change (official requirement): keep every currently active
+  // tool — built-ins and other extensions' tools included — and enable Tier 1.
+  function activateChannel(): void {
+    if (activated) return;
+    pi.setActiveTools([...new Set([...pi.getActiveTools(), ...TIER1_TOOL_NAMES])]);
+    activated = true;
+  }
+
+  pi.on("session_start", () => {
+    // Dormant presentation for this runtime session: drop any Tier 1 tools
+    // from the active set (registration makes tools active by default) while
+    // preserving built-ins, other extensions' tools, and the gateway itself.
+    // Resetting `activated` keeps activation scoped to the current session.
+    activated = false;
+    pi.setActiveTools(pi.getActiveTools().filter((name) => !TIER1_TOOL_SET.has(name)));
+
+    // Self identity bootstrap (PROTOCOL.md §6.3), once per runtime session:
+    // fire-and-forget so session start never blocks or fails on Herdr IO;
+    // communication paths fall back through getSelfContext(). Failures
+    // surface later as SELF_UNNAMED.
+    void ensureSelfName().catch(() => {});
+  });
+
+  pi.on("before_agent_start", (event) => {
+    if (!activated) return undefined;
+    return { systemPrompt: `${event.systemPrompt}\n\n${COMMUNICATION_CONTRACT}` };
+  });
+}

package/src/protocol.ts

@@ -0,0 +1,284 @@
+/**
+ * Herdr Link protocol core — pure protocol types and helpers.
+ *
+ * No Herdr IO in this file. The canonical specification is PROTOCOL.md
+ * at the repository root; this module is its machine-readable core.
+ */
+
+export const PROTOCOL_ID = "herdr-link/1" as const;
+
+/** Herdr agent-name rule: `[a-z][a-z0-9_-]{0,31}`, unique among live agents. */
+export const AGENT_NAME_RE = /^[a-z][a-z0-9_-]{0,31}$/;
+/** Message id rule from PROTOCOL.md §2.3: `hl_<timestamp>_<random>`. */
+export const MESSAGE_ID_RE = /^hl_[a-z0-9]+_[a-z0-9]+$/;
+
+/* ------------------------------------------------------------------ *
+ * Naming tiers (blueprint v2)
+ *
+ * Tier 0 is the Herdr Link gateway itself — the host registration
+ * namespace every runtime presents its tools against (underscore form;
+ * 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).
+ * ------------------------------------------------------------------ */
+
+/** 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_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;
+
+/* ------------------------------------------------------------------ *
+ * Agent state (blueprint v2)
+ * ------------------------------------------------------------------ */
+
+/** Live activity states; any unrecognized Herdr status maps to "unknown". */
+export const AGENT_STATES = ["idle", "working", "blocked", "done", "unknown"] as const;
+
+export type AgentState = (typeof AGENT_STATES)[number];
+
+/** Maps a raw Herdr status value onto the closed AgentState vocabulary. */
+export function toAgentState(value: unknown): AgentState {
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if ((AGENT_STATES as readonly string[]).includes(normalized)) {
+      return normalized as AgentState;
+    }
+  }
+  return "unknown";
+}
+
+/** A named agent together with its live activity state. Never carries topology ids. */
+export interface PeerInfo {
+  name: string;
+  state: AgentState;
+}
+
+/**
+ * Instant peer directory (blueprint v2): same-workspace live agents only,
+ * self excluded. Generated fresh on every call; never persisted or cached.
+ */
+export interface PeerDirectory {
+  self: PeerInfo;
+  peers: PeerInfo[];
+}
+
+/**
+ * Live identity of one agent, freshly resolved from Herdr on every call.
+ * Ambient environment values (e.g. HERDR_WORKSPACE_ID) are never a
+ * substitute for these fields.
+ */
+export interface AgentContext {
+  /** Valid Herdr agent name. */
+  name: string;
+  /** Authoritative workspace id from the live record; "" when unreported (comparisons fail closed). */
+  workspace_id: string;
+  /** Pane currently hosting the agent. */
+  pane_id: string;
+  /** Live activity state mapped onto AgentState. */
+  agent_status: AgentState;
+}
+
+/** The cross-agent message envelope (PROTOCOL.md §2). Minimal fields only. */
+export interface HerdrLinkEnvelope {
+  protocol: typeof PROTOCOL_ID;
+  id: string;
+  from: string;
+  to: string;
+  reply_to?: string;
+  message: string;
+}
+
+/** V1 error codes (PROTOCOL.md §7). All are local tool failures, never an envelope. */
+export const LINK_ERROR_CODES = [
+  "NOT_IN_HERDR",
+  "SELF_UNNAMED",
+  "PEER_NOT_FOUND",
+  "SEND_FAILED",
+  "CLOSE_FAILED",
+] as const;
+
+export type LinkErrorCode = (typeof LINK_ERROR_CODES)[number];
+
+/** Standard failure for every Herdr Link tool. */
+export class HerdrLinkError extends Error {
+  readonly code: LinkErrorCode;
+
+  constructor(code: LinkErrorCode, detail?: string) {
+    super(detail ? `${code}: ${detail}` : code);
+    this.name = "HerdrLinkError";
+    this.code = code;
+  }
+}
+
+/** Stable Agent-facing details; raw Herdr diagnostics remain internal to the error object. */
+export const AGENT_ERROR_DETAILS: Record<LinkErrorCode, string> = {
+  NOT_IN_HERDR: "Herdr environment is unavailable",
+  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",
+};
+
+/** Formats a Link failure without exposing raw Herdr topology or CLI details. */
+export function formatAgentFacingError(error: unknown, fallbackCode: LinkErrorCode): string {
+  const code = error instanceof HerdrLinkError ? error.code : fallbackCode;
+  return `${code}: ${AGENT_ERROR_DETAILS[code]}`;
+}
+
+/** Creates a unique message id: `hl_` + base36 timestamp + random suffix. */
+export function createMessageId(): string {
+  const ts = Date.now().toString(36);
+  const rand = Math.random().toString(36).slice(2, 10) || "0";
+  return `hl_${ts}_${rand}`;
+}
+
+export function isValidAgentName(name: string): boolean {
+  return AGENT_NAME_RE.test(name);
+}
+
+export function isValidMessageId(id: string): boolean {
+  return MESSAGE_ID_RE.test(id);
+}
+
+export interface BuildEnvelopeInput {
+  from: string;
+  to: string;
+  message: string;
+  reply_to?: string;
+}
+
+/**
+ * Builds a validated envelope. `from` is supplied by the Adapter from Herdr
+ * identity — the model never submits it. `to`/`message` originate from the
+ * model and are validated here.
+ */
+export function buildEnvelope(input: BuildEnvelopeInput): HerdrLinkEnvelope {
+  if (!isValidAgentName(input.from)) {
+    throw new HerdrLinkError(
+      "SELF_UNNAMED",
+      `self agent name "${input.from}" is not a valid Herdr agent name`,
+    );
+  }
+  if (!input.to || !isValidAgentName(input.to)) {
+    throw new HerdrLinkError(
+      "PEER_NOT_FOUND",
+      `target agent name "${input.to}" is not a valid Herdr agent name`,
+    );
+  }
+  if (typeof input.message !== "string" || input.message.trim() === "") {
+    throw new HerdrLinkError("SEND_FAILED", "message must be a non-empty string");
+  }
+  if (input.reply_to !== undefined && !isValidMessageId(input.reply_to)) {
+    throw new HerdrLinkError(
+      "SEND_FAILED",
+      "reply_to must be a valid herdr-link/1 message id when present",
+    );
+  }
+  const envelope: HerdrLinkEnvelope = {
+    protocol: PROTOCOL_ID,
+    id: createMessageId(),
+    from: input.from,
+    to: input.to,
+    message: input.message,
+  };
+  if (input.reply_to !== undefined) {
+    envelope.reply_to = input.reply_to;
+  }
+  return envelope;
+}
+
+/**
+ * Type guard for receiving side (PROTOCOL.md §3 rule 3): an incoming payload
+ * is a Herdr Link message iff it carries `protocol: "herdr-link/1"` and a
+ * string `message` body from a named `from` agent.
+ */
+export function isHerdrLinkEnvelope(value: unknown): value is HerdrLinkEnvelope {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    v.protocol === PROTOCOL_ID &&
+    typeof v.id === "string" &&
+    isValidMessageId(v.id) &&
+    typeof v.from === "string" &&
+    isValidAgentName(v.from) &&
+    typeof v.to === "string" &&
+    isValidAgentName(v.to) &&
+    typeof v.message === "string" &&
+    v.message.trim() !== "" &&
+    (v.reply_to === undefined || (typeof v.reply_to === "string" && isValidMessageId(v.reply_to)))
+  );
+}
+
+/* ------------------------------------------------------------------ *
+ * Inbound delivery wrapper (blueprint v2)
+ *
+ * `herdr agent prompt` carries a self-describing wrapper around the
+ * envelope so a dormant receiver (adapter loaded, model not mid-exchange)
+ * can recognize the delivery and activate a reply addressed by reply_to.
+ * The wrapper is transport dressing ONLY: the envelope keeps exactly the
+ * minimal herdr-link/1 fields and is embedded verbatim as the final line.
+ * ------------------------------------------------------------------ */
+
+/** Marks the start of an inbound delivery wrapper. */
+export const INBOUND_WRAPPER_MARKER = `[${PROTOCOL_ID}]`;
+
+/** Builds the self-describing inbound wrapper delivered via `agent prompt`. */
+export function buildInboundWrapper(envelope: HerdrLinkEnvelope): string {
+  const lines: string[] = [
+    `${INBOUND_WRAPPER_MARKER} inter-agent message delivered through the ${HERDR_LINK_GATEWAY} gateway.`,
+    `From: ${envelope.from}`,
+    `Message id: ${envelope.id}`,
+  ];
+  if (envelope.reply_to !== undefined) {
+    lines.push(`Reply to: ${envelope.reply_to}`);
+  }
+  lines.push(
+    "",
+    "The JSON object below is the complete herdr-link/1 envelope; the text around it is delivery metadata and is not part of the message.",
+    'Treat the envelope\'s "message" field as content sent by the agent named in "from".',
+    "If a reply is needed, activate the Herdr Link gateway when dormant, then use the active Herdr Link send capability to send to envelope.from with reply_to set to envelope.id.",
+    "",
+    JSON.stringify(envelope),
+  );
+  return lines.join("\n");
+}
+
+/**
+ * Receiver-side counterpart: extracts the envelope from a delivery text by
+ * scanning bottom-up for a line that parses as a valid herdr-link/1
+ * envelope. Returns undefined for non-delivery input.
+ */
+export function extractInboundEnvelope(text: string): HerdrLinkEnvelope | undefined {
+  const lines = text.split("\n");
+  for (let index = lines.length - 1; index >= 0; index--) {
+    const line = lines[index]!.trim();
+    if (!line.startsWith("{")) continue;
+    try {
+      const candidate: unknown = JSON.parse(line);
+      if (isHerdrLinkEnvelope(candidate)) return candidate;
+    } catch {
+      // Not JSON on this line; keep scanning upwards.
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Active Agent Communication Contract injected verbatim into the model.
+ * Compact form: same-workspace addressing, send/reply/close semantics only.
+ */
+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.
+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".
+5. When replying, send to the received "from" agent and set reply_to to the received "id".
+6. Use herdr_link_close only when you have already decided that a named agent's pane should be closed. If a final message is needed, call close in a later tool step after herdr_link_send returns "sent".
+7. Never use a raw pane id, UI focus, terminal input, or the Herdr CLI as an inter-agent channel; agent names are the only addresses.
+8. Agents outside your workspace are invisible: they never appear in peers and messages addressed to them fail.`;