@sjawhar/opencode-legion-envoy 0.1.0-alpha.0 → 0.1.0

package/AGENTS.md

@@ -0,0 +1,33 @@
+# Envoy Plugin Package
+
+OpenCode plugin package for Legion's Envoy subsystem.
+
+## Overview
+
+This plugin exposes the Envoy tools and maintains the live session registry metadata Envoy needs for hot delivery.
+
+It is the user-facing bridge between OpenCode sessions and Envoy transport.
+
+## Where to look
+
+| Task                | Location               | Notes                                                              |
+| ------------------- | ---------------------- | ------------------------------------------------------------------ |
+| Tool definitions    | `src/index.ts`         | `envoy_subscribe`, `envoy_unsubscribe`, `envoy_list`, `envoy_send` |
+| Packaging metadata  | `package.json`         | npm identity, build scripts                                        |
+| Distribution output | `dist/index.js`        | built plugin consumed by OpenCode                                  |
+| Host rollout helper | `scripts/sync-host.sh` | sync dist + shim to remote host                                    |
+
+## Critical conventions
+
+- Tool descriptions must be self-describing enough that agents can infer correct topic formats.
+- Slack examples must use real `team_id` values, not workspace slugs.
+- This package owns the session-registry/port-backfill behavior now; do not split that back into a second plugin casually.
+- Keep the plugin source-of-truth here even if a dotfiles shim is still used for rollout convenience.
+
+## Topic reminders
+
+- Agent: `notifications.agent.<session_id>`
+- GitHub: `notifications.github.<owner>.<repo>.<kind>`
+- Slack: `notifications.slack.<team_id>.<channel_id>.<message|mention>`
+
+If you are unsure what a session is subscribed to, use `envoy_list()`.

package/README.md

@@ -11,11 +11,23 @@ This package exposes:
 
 It also maintains the live session registry metadata needed for Envoy to discover OpenCode sessions and their API ports.
 
+Slack topic examples must use the real Slack `team_id`, for example:
+
+- `notifications.slack.T09FRELLTS8.C0A0DHVU8HE.mention`
+
+Do not use workspace slugs like `trajectorylabs` in the topic path.
+
 ## Sync to another machine
 
 ```bash
-cd ~/legion/default/packages/envoy-plugin
-./scripts/sync-host.sh sami@sami
+# From the repo root:
+./packages/envoy-plugin/scripts/sync-host.sh sami@sami
+
+# Or via the combined envoy sync:
+./scripts/sync-envoy-host.sh sami@sami
 ```
 
-This syncs the built plugin dist and the dotfiles shim to the target host.
+The sync script downloads the latest envoy-plugin release tarball from GitHub,
+extracts it to `~/legion/default/packages/envoy-plugin/` on the remote host, and
+updates the remote's `opencode.json` to use a `file://` reference instead of the
+npm package. Requires `gh` CLI on the machine running the script.

package/dist/index.js

@@ -15,8 +15,7 @@ var __export = (target, all) => {
 };
 
 // src/index.ts
-import { execFileSync } from "child_process";
-import { readFileSync, writeFileSync } from "fs";
+import { readFileSync, unlinkSync, writeFileSync } from "fs";
 
 // ../../node_modules/.bun/zod@4.1.8/node_modules/zod/v4/classic/external.js
 var exports_external = {};
@@ -12339,6 +12338,31 @@ function tool(input) {
 }
 tool.schema = exports_external;
 
+// src/port.ts
+import { execFileSync } from "child_process";
+function resolvePort(serverUrl, exec = execFileSync) {
+  const urlPort = Number.parseInt(serverUrl.port, 10);
+  if (Number.isFinite(urlPort) && urlPort > 0)
+    return urlPort;
+  try {
+    const output = exec("ss", ["-tlnp"], { encoding: "utf-8" });
+    for (const line of output.split(`
+`)) {
+      if (!line.includes(`pid=${process.pid}`))
+        continue;
+      const parts = line.trim().split(/\s+/);
+      const local = parts[3];
+      const match = local?.match(/:(\d+)$/);
+      if (!match)
+        continue;
+      const port = Number.parseInt(match[1], 10);
+      if (Number.isFinite(port) && port > 0)
+        return port;
+    }
+  } catch {}
+  return null;
+}
+
 // src/index.ts
 var root = process.env.ENVOY_URL ?? "http://127.0.0.1:9020";
 async function call(path, init) {
@@ -12349,47 +12373,44 @@ async function call(path, init) {
   return text;
 }
 var src_default = async (input) => {
-  const shellPid = process.env.OC_SHELL_PID;
   const registryDir = process.env.OC_REGISTRY;
-  const file2 = shellPid && registryDir ? `${registryDir}/${shellPid}.json` : null;
   let activeSessionID = null;
-  const update = (patch) => {
+  let _activeFile = null;
+  const registryFile = (sessionID) => registryDir ? `${registryDir}/${sessionID}.json` : null;
+  const update = (sessionID, patch) => {
+    const file2 = registryFile(sessionID);
     if (!file2)
       return;
     try {
-      const data = JSON.parse(readFileSync(file2, "utf-8"));
+      let data = {};
+      try {
+        data = JSON.parse(readFileSync(file2, "utf-8"));
+      } catch {
+        data = { pid: process.pid, dir: process.cwd(), started: new Date().toISOString() };
+      }
       Object.assign(data, patch);
       writeFileSync(file2, `${JSON.stringify(data)}
 `);
+      registryFiles.add(file2);
     } catch {}
   };
+  let portWarningLogged = false;
   const currentPort = () => {
-    const value = Number.parseInt(input.serverUrl.port, 10);
-    if (Number.isFinite(value) && value > 0)
-      return value;
-    try {
-      const output = execFileSync("ss", ["-tlnp"], { encoding: "utf-8" });
-      for (const line of output.split(`
-`)) {
-        if (!line.includes(`pid=${process.pid}`))
-          continue;
-        const parts = line.trim().split(/\s+/);
-        const local = parts[3];
-        const match = local?.match(/:(\d+)$/);
-        if (!match)
-          continue;
-        const port = Number.parseInt(match[1], 10);
-        if (Number.isFinite(port) && port > 0)
-          return port;
-      }
-    } catch {}
-    return null;
+    const port = resolvePort(input.serverUrl);
+    if (!port && !portWarningLogged) {
+      portWarningLogged = true;
+      console.error(`[envoy-plugin] Could not resolve serve port: serverUrl=${input.serverUrl.href}, pid=${process.pid}`);
+    }
+    if (port)
+      portWarningLogged = false;
+    return port;
   };
-  const syncPort = () => {
+  const syncPort = (sessionID) => {
     const value = currentPort();
     if (!value)
       return false;
-    update({ port: value });
+    if (sessionID)
+      update(sessionID, { port: value });
     return true;
   };
   const fetchSession = async (sessionID) => {
@@ -12403,29 +12424,71 @@ var src_default = async (input) => {
       return null;
     }
   };
-  if (file2) {
+  const registryFiles = new Set;
+  if (registryDir) {
     syncPort();
     const timer = setInterval(() => {
-      if (syncPort())
+      if (syncPort(activeSessionID ?? undefined))
         clearInterval(timer);
     }, 1000);
+    const heartbeatInterval = setInterval(() => {
+      if (!activeSessionID)
+        return;
+      const port = currentPort();
+      if (!port)
+        return;
+      call("/v1/interests/subscribe", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          session_id: activeSessionID,
+          dir: process.cwd(),
+          topics: [`notifications.agent.${activeSessionID}`],
+          port
+        })
+      }).catch(() => {});
+    }, 2 * 60 * 1000);
+    process.on("exit", () => {
+      clearInterval(heartbeatInterval);
+      for (const f of registryFiles) {
+        try {
+          unlinkSync(f);
+        } catch {}
+      }
+    });
   }
   return {
-    event: file2 ? async ({ event }) => {
-      syncPort();
+    event: registryDir ? async ({ event }) => {
+      if (activeSessionID)
+        syncPort(activeSessionID);
       if (event.type === "session.status" && event.properties?.status?.type === "busy") {
         const sessionID = event.properties?.sessionID;
         if (sessionID && sessionID !== activeSessionID) {
           activeSessionID = sessionID;
+          _activeFile = registryFile(sessionID);
           const session = await fetchSession(sessionID);
           if (session)
-            update({ session });
+            update(sessionID, { session });
+          syncPort(sessionID);
+          const port = currentPort();
+          if (port) {
+            call("/v1/interests/subscribe", {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({
+                session_id: sessionID,
+                dir: process.cwd(),
+                topics: [`notifications.agent.${sessionID}`],
+                port
+              })
+            }).catch(() => {});
+          }
         }
       }
       if (event.type === "session.updated") {
         const info = event.properties?.info;
         if (info && info.id === activeSessionID) {
-          update({ session: { id: info.id, title: info.title || "" } });
+          update(info.id, { session: { id: info.id, title: info.title || "" } });
         }
       }
       if (event.type === "session.idle") {
@@ -12433,15 +12496,15 @@ var src_default = async (input) => {
         if (sessionID && sessionID === activeSessionID) {
           const session = await fetchSession(sessionID);
           if (session)
-            update({ session });
+            update(sessionID, { session });
         }
       }
     } : undefined,
     tool: {
       envoy_subscribe: tool({
-        description: "Subscribe this session to envoy notification topics",
+        description: "Subscribe this session to Envoy notification topics. Use exact NATS-style topic strings such as notifications.agent.<session_id>, notifications.github.<owner>.<repo>.pr, notifications.github.<owner>.<repo>.issue, notifications.github.<owner>.<repo>.comment, notifications.github.<owner>.<repo>.ci, notifications.slack.<team_id>.<channel_id>.message, or notifications.slack.<team_id>.<channel_id>.mention. Use this when a session should RECEIVE future events.",
         args: {
-          topics: tool.schema.array(tool.schema.string()).describe("NATS-style topic patterns to subscribe to")
+          topics: tool.schema.array(tool.schema.string()).describe("NATS-style topic patterns to subscribe to. Examples: notifications.agent.ses_123, notifications.github.trajectory-labs-pbc.agent-c.pr, notifications.slack.T09FRELLTS8.C0A0DHVU8HE.mention")
         },
         async execute(args, ctx) {
           ctx.metadata({ title: "Envoy subscribe" });
@@ -12451,13 +12514,14 @@ var src_default = async (input) => {
             body: JSON.stringify({
               session_id: ctx.sessionID,
               dir: ctx.directory,
-              topics: args.topics
+              topics: args.topics,
+              port: currentPort() ?? 0
             })
           });
         }
       }),
       envoy_unsubscribe: tool({
-        description: "Unsubscribe this session from envoy topics, or all if omitted",
+        description: "Unsubscribe this session from Envoy topics, or remove all current subscriptions if topics are omitted.",
         args: {
           topics: tool.schema.array(tool.schema.string()).optional().describe("Topics to remove, or omit to remove all")
         },
@@ -12474,7 +12538,7 @@ var src_default = async (input) => {
         }
       }),
       envoy_list: tool({
-        description: "List envoy subscriptions for this session",
+        description: "List the current Envoy topic subscriptions for this session so you can confirm the exact topic shapes that are active.",
         args: {},
         async execute(_args, ctx) {
           ctx.metadata({ title: "Envoy list" });
@@ -12482,10 +12546,10 @@ var src_default = async (input) => {
         }
       }),
       envoy_send: tool({
-        description: "Send an envoy agent-to-agent message to another session",
+        description: "Send an Envoy agent-to-agent message directly to another session by session ID. Use this for coordination between agents or to notify a known controller/worker session. This is for SEND, not subscription.",
         args: {
-          target_session: tool.schema.string().describe("Target session ID"),
-          message: tool.schema.string().describe("Message to deliver")
+          target_session: tool.schema.string().describe("Target OpenCode session ID, e.g. ses_2e6ca3034ffejVikSZ8mDwk0mR"),
+          message: tool.schema.string().describe("Message body to deliver to that session as a new user turn/notification")
         },
         async execute(args, ctx) {
           ctx.metadata({ title: "Envoy send" });
@@ -12499,6 +12563,25 @@ var src_default = async (input) => {
             })
           });
         }
+      }),
+      envoy_publish: tool({
+        description: "Publish an Envoy message to any topic. Use for broadcast to named topics like notifications.legion.controller, team channels, or custom routing. Subscribers matching the topic will receive the message. This is for BROADCAST, not session-targeted delivery (use envoy_send for that).",
+        args: {
+          topic: tool.schema.string().describe("NATS-style topic to publish to, e.g. notifications.legion.controller"),
+          message: tool.schema.string().describe("Message body to broadcast")
+        },
+        async execute(args, ctx) {
+          ctx.metadata({ title: "Envoy publish" });
+          return call("/v1/messages/publish", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              source_session: ctx.sessionID,
+              topic: args.topic,
+              message: args.message
+            })
+          });
+        }
       })
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/sync-host.sh

@@ -2,7 +2,55 @@
 set -euo pipefail
 
 host="${1:?usage: sync-host.sh user@host}"
-root="$(cd "$(dirname "$0")/../../.." && pwd)"
 
-rsync -az "$root/packages/envoy-plugin/dist/" "$host:~/legion/default/packages/envoy-plugin/dist/"
-rsync -az "$HOME/.dotfiles/opencode/plugins/envoy.ts" "$host:~/.dotfiles/opencode/plugins/envoy.ts"
+PLUGIN_DIR="legion/default/packages/envoy-plugin"
+PLUGIN_REF="file://{env:HOME}/${PLUGIN_DIR}/dist/index.js"
+REPO="sjawhar/legion"
+
+# Find latest envoy release tag
+tag=$(gh release list --repo "$REPO" --limit 10 --json tagName \
+  --jq '[.[] | select(.tagName | startswith("legion-envoy-"))][0].tagName')
+if [ -z "$tag" ]; then
+  echo "ERROR: No legion-envoy release found" >&2
+  exit 1
+fi
+echo "Using release: $tag"
+
+# Download plugin tarball
+tmpdir=$(mktemp -d)
+trap 'rm -rf "$tmpdir"' EXIT
+
+gh release download "$tag" \
+  --repo "$REPO" \
+  --pattern '*.tgz' \
+  --dir "$tmpdir" \
+  --clobber
+
+tgz=$(find "$tmpdir" -name '*.tgz' -print -quit)
+if [ -z "$tgz" ]; then
+  echo "ERROR: No .tgz found in release $tag" >&2
+  exit 1
+fi
+echo "Downloaded: $(basename "$tgz")"
+
+# Install on remote: extract tarball (strip package/ prefix from npm pack output)
+ssh "$host" "rm -rf ~/${PLUGIN_DIR} && mkdir -p ~/${PLUGIN_DIR}"
+scp -q "$tgz" "$host:/tmp/envoy-plugin.tgz"
+ssh "$host" "tar xzf /tmp/envoy-plugin.tgz --strip-components=1 -C ~/${PLUGIN_DIR} && rm /tmp/envoy-plugin.tgz"
+echo "Installed plugin to ~/${PLUGIN_DIR}"
+
+# Update opencode.json: replace npm package reference with file:// path
+# Resolves symlinks so we don't clobber dotfiles symlink structure
+ssh "$host" "
+  CONFIG=\$(readlink -f \$HOME/.config/opencode/opencode.json 2>/dev/null || echo \$HOME/.config/opencode/opencode.json)
+  if [ -f \"\$CONFIG\" ]; then
+    jq --arg ref '$PLUGIN_REF' \\
+      '(.plugin // []) |= [.[] | if (test(\"opencode-legion-envoy\") and (test(\"^file://\") | not)) then \$ref else . end]' \\
+      \"\$CONFIG\" > /tmp/opencode.json.tmp && mv /tmp/opencode.json.tmp \"\$CONFIG\"
+    echo \"Updated opencode.json: \$CONFIG\"
+  else
+    echo \"WARNING: opencode.json not found at \$CONFIG — add plugin manually: $PLUGIN_REF\"
+  fi
+"
+
+echo "Done: $host envoy-plugin synced from release $tag"

package/src/__tests__/port.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it, mock } from "bun:test";
+import { resolvePort } from "../port";
+
+describe("resolvePort", () => {
+  const noopExec = (() => {
+    throw new Error("ss not available");
+  }) as typeof import("node:child_process").execFileSync;
+
+  const ssOutput = (pid: number, port: number) =>
+    [
+      "State  Recv-Q Send-Q Local Address:Port  Peer Address:Port Process",
+      `LISTEN 0      511    127.0.0.1:${port}  0.0.0.0:*  users:(("bun",pid=${pid},fd=6))`,
+      "",
+    ].join("\n");
+
+  describe("URL port extraction", () => {
+    it("returns port from standard non-default URL", () => {
+      expect(resolvePort(new URL("http://127.0.0.1:4096"), noopExec)).toBe(4096);
+    });
+
+    it("returns port for high serve ports", () => {
+      expect(resolvePort(new URL("http://127.0.0.1:13381"), noopExec)).toBe(13381);
+    });
+
+    it("returns port for localhost URLs", () => {
+      expect(resolvePort(new URL("http://localhost:4096"), noopExec)).toBe(4096);
+    });
+
+    it("returns port for IPv6 URLs", () => {
+      expect(resolvePort(new URL("http://[::1]:4096"), noopExec)).toBe(4096);
+    });
+  });
+
+  describe("ss fallback", () => {
+    it("uses ss when URL has no port (default HTTP)", () => {
+      const exec = mock(() => ssOutput(process.pid, 4096));
+      expect(resolvePort(new URL("http://127.0.0.1"), exec as never)).toBe(4096);
+      expect(exec).toHaveBeenCalledWith("ss", ["-tlnp"], { encoding: "utf-8" });
+    });
+
+    it("uses ss when URL port is 0", () => {
+      // URL("http://127.0.0.1:0").port is "0", which is not > 0
+      const exec = mock(() => ssOutput(process.pid, 13381));
+      expect(resolvePort(new URL("http://127.0.0.1:0"), exec as never)).toBe(13381);
+    });
+
+    it("ignores ss lines with different PIDs", () => {
+      const exec = mock(() => ssOutput(99999, 4096));
+      expect(resolvePort(new URL("http://127.0.0.1"), exec as never)).toBeNull();
+    });
+
+    it("handles multiple ss entries and picks the matching PID", () => {
+      const output = [
+        "State  Recv-Q Send-Q Local Address:Port  Peer Address:Port Process",
+        `LISTEN 0      511    127.0.0.1:8080  0.0.0.0:*  users:(("node",pid=99999,fd=6))`,
+        `LISTEN 0      511    127.0.0.1:4096  0.0.0.0:*  users:(("bun",pid=${process.pid},fd=7))`,
+        "",
+      ].join("\n");
+      const exec = mock(() => output);
+      expect(resolvePort(new URL("http://127.0.0.1"), exec as never)).toBe(4096);
+    });
+
+    it("handles IPv6 listening addresses in ss output", () => {
+      const output = [
+        "State  Recv-Q Send-Q Local Address:Port  Peer Address:Port Process",
+        `LISTEN 0      511    [::]:4096  [::]:*  users:(("bun",pid=${process.pid},fd=6))`,
+        "",
+      ].join("\n");
+      const exec = mock(() => output);
+      expect(resolvePort(new URL("http://127.0.0.1"), exec as never)).toBe(4096);
+    });
+  });
+  describe("failure cases", () => {
+    it("returns null when ss is not available", () => {
+      expect(resolvePort(new URL("http://127.0.0.1"), noopExec)).toBeNull();
+    });
+
+    it("returns null when ss returns empty output", () => {
+      const exec = mock(() => "");
+      expect(resolvePort(new URL("http://127.0.0.1"), exec as never)).toBeNull();
+    });
+  });
+
+  describe("edge cases", () => {
+    it("URL.port is empty string for default HTTP port 80", () => {
+      // http://127.0.0.1:80 → URL.port is "" (80 is default for http)
+      const url = new URL("http://127.0.0.1:80");
+      expect(url.port).toBe("");
+      const exec = mock(() => ssOutput(process.pid, 4096));
+      expect(resolvePort(url, exec as never)).toBe(4096);
+    });
+
+    it("URL.port is empty string for default HTTPS port 443", () => {
+      const url = new URL("https://127.0.0.1:443");
+      expect(url.port).toBe("");
+      const exec = mock(() => ssOutput(process.pid, 4096));
+      expect(resolvePort(url, exec as never)).toBe(4096);
+    });
+
+    it("does not use ss fallback when URL port is valid", () => {
+      const exec = mock(() => ssOutput(process.pid, 9999));
+      expect(resolvePort(new URL("http://127.0.0.1:4096"), exec as never)).toBe(4096);
+      expect(exec).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/index.ts

@@ -1,6 +1,6 @@
-import { execFileSync } from "node:child_process";
-import { readFileSync, writeFileSync } from "node:fs";
+import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { tool } from "@opencode-ai/plugin/tool";
+import { resolvePort } from "./port";
 
 const root = process.env.ENVOY_URL ?? "http://127.0.0.1:9020";
 
@@ -12,44 +12,46 @@ async function call(path: string, init?: RequestInit) {
 }
 
 export default async (input: { serverUrl: URL }) => {
-  const shellPid = process.env.OC_SHELL_PID;
   const registryDir = process.env.OC_REGISTRY;
-  const file = shellPid && registryDir ? `${registryDir}/${shellPid}.json` : null;
   let activeSessionID: string | null = null;
+  let _activeFile: string | null = null;
 
-  const update = (patch: Record<string, unknown>) => {
+  const registryFile = (sessionID: string) =>
+    registryDir ? `${registryDir}/${sessionID}.json` : null;
+
+  const update = (sessionID: string, patch: Record<string, unknown>) => {
+    const file = registryFile(sessionID);
     if (!file) return;
     try {
-      const data = JSON.parse(readFileSync(file, "utf-8"));
+      let data: Record<string, unknown> = {};
+      try {
+        data = JSON.parse(readFileSync(file, "utf-8"));
+      } catch {
+        data = { pid: process.pid, dir: process.cwd(), started: new Date().toISOString() };
+      }
       Object.assign(data, patch);
       writeFileSync(file, `${JSON.stringify(data)}\n`);
+      registryFiles.add(file);
     } catch {}
   };
 
+  let portWarningLogged = false;
   const currentPort = () => {
-    const value = Number.parseInt(input.serverUrl.port, 10);
-    if (Number.isFinite(value) && value > 0) return value;
-
-    try {
-      const output = execFileSync("ss", ["-tlnp"], { encoding: "utf-8" });
-      for (const line of output.split("\n")) {
-        if (!line.includes(`pid=${process.pid}`)) continue;
-        const parts = line.trim().split(/\s+/);
-        const local = parts[3];
-        const match = local?.match(/:(\d+)$/);
-        if (!match) continue;
-        const port = Number.parseInt(match[1], 10);
-        if (Number.isFinite(port) && port > 0) return port;
-      }
-    } catch {}
-
-    return null;
+    const port = resolvePort(input.serverUrl);
+    if (!port && !portWarningLogged) {
+      portWarningLogged = true;
+      console.error(
+        `[envoy-plugin] Could not resolve serve port: serverUrl=${input.serverUrl.href}, pid=${process.pid}`
+      );
+    }
+    if (port) portWarningLogged = false;
+    return port;
   };
 
-  const syncPort = () => {
+  const syncPort = (sessionID?: string) => {
     const value = currentPort();
     if (!value) return false;
-    update({ port: value });
+    if (sessionID) update(sessionID, { port: value });
     return true;
   };
 
@@ -64,17 +66,49 @@ export default async (input: { serverUrl: URL }) => {
     }
   };
 
-  if (file) {
+  // Track all registry files this process created, clean up on exit
+  const registryFiles = new Set<string>();
+
+  if (registryDir) {
     syncPort();
     const timer = setInterval(() => {
-      if (syncPort()) clearInterval(timer);
+      if (syncPort(activeSessionID ?? undefined)) clearInterval(timer);
     }, 1000);
+
+    // Heartbeat: re-subscribe every 2 minutes to refresh envoy_sessions TTL (5-min)
+    const heartbeatInterval = setInterval(
+      () => {
+        if (!activeSessionID) return;
+        const port = currentPort();
+        if (!port) return;
+        call("/v1/interests/subscribe", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            session_id: activeSessionID,
+            dir: process.cwd(),
+            topics: [`notifications.agent.${activeSessionID}`],
+            port,
+          }),
+        }).catch(() => {});
+      },
+      2 * 60 * 1000
+    );
+
+    process.on("exit", () => {
+      clearInterval(heartbeatInterval);
+      for (const f of registryFiles) {
+        try {
+          unlinkSync(f);
+        } catch {}
+      }
+    });
   }
 
   return {
-    event: file
+    event: registryDir
       ? async ({ event }: { event: { type?: string; properties?: Record<string, unknown> } }) => {
-          syncPort();
+          if (activeSessionID) syncPort(activeSessionID);
 
           if (
             event.type === "session.status" &&
@@ -83,15 +117,29 @@ export default async (input: { serverUrl: URL }) => {
             const sessionID = event.properties?.sessionID as string | undefined;
             if (sessionID && sessionID !== activeSessionID) {
               activeSessionID = sessionID;
+              _activeFile = registryFile(sessionID);
               const session = await fetchSession(sessionID);
-              if (session) update({ session });
+              if (session) update(sessionID, { session });
+              syncPort(sessionID);
+              const port = currentPort();
+              if (port) {
+                call("/v1/interests/subscribe", {
+                  method: "POST",
+                  headers: { "Content-Type": "application/json" },
+                  body: JSON.stringify({
+                    session_id: sessionID,
+                    dir: process.cwd(),
+                    topics: [`notifications.agent.${sessionID}`],
+                    port,
+                  }),
+                }).catch(() => {});
+              }
             }
           }
-
           if (event.type === "session.updated") {
             const info = event.properties?.info as { id?: string; title?: string } | undefined;
             if (info && info.id === activeSessionID) {
-              update({ session: { id: info.id, title: info.title || "" } });
+              update(info.id, { session: { id: info.id, title: info.title || "" } });
             }
           }
 
@@ -99,18 +147,21 @@ export default async (input: { serverUrl: URL }) => {
             const sessionID = event.properties?.sessionID as string | undefined;
             if (sessionID && sessionID === activeSessionID) {
               const session = await fetchSession(sessionID);
-              if (session) update({ session });
+              if (session) update(sessionID, { session });
             }
           }
         }
       : undefined,
     tool: {
       envoy_subscribe: tool({
-        description: "Subscribe this session to envoy notification topics",
+        description:
+          "Subscribe this session to Envoy notification topics. Use exact NATS-style topic strings such as notifications.agent.<session_id>, notifications.github.<owner>.<repo>.pr, notifications.github.<owner>.<repo>.issue, notifications.github.<owner>.<repo>.comment, notifications.github.<owner>.<repo>.ci, notifications.slack.<team_id>.<channel_id>.message, or notifications.slack.<team_id>.<channel_id>.mention. Use this when a session should RECEIVE future events.",
         args: {
           topics: tool.schema
             .array(tool.schema.string())
-            .describe("NATS-style topic patterns to subscribe to"),
+            .describe(
+              "NATS-style topic patterns to subscribe to. Examples: notifications.agent.ses_123, notifications.github.trajectory-labs-pbc.agent-c.pr, notifications.slack.T09FRELLTS8.C0A0DHVU8HE.mention"
+            ),
         },
         async execute(args, ctx) {
           ctx.metadata({ title: "Envoy subscribe" });
@@ -121,12 +172,14 @@ export default async (input: { serverUrl: URL }) => {
               session_id: ctx.sessionID,
               dir: ctx.directory,
               topics: args.topics,
+              port: currentPort() ?? 0,
             }),
           });
         },
       }),
       envoy_unsubscribe: tool({
-        description: "Unsubscribe this session from envoy topics, or all if omitted",
+        description:
+          "Unsubscribe this session from Envoy topics, or remove all current subscriptions if topics are omitted.",
         args: {
           topics: tool.schema
             .array(tool.schema.string())
@@ -146,7 +199,8 @@ export default async (input: { serverUrl: URL }) => {
         },
       }),
       envoy_list: tool({
-        description: "List envoy subscriptions for this session",
+        description:
+          "List the current Envoy topic subscriptions for this session so you can confirm the exact topic shapes that are active.",
         args: {},
         async execute(_args, ctx) {
           ctx.metadata({ title: "Envoy list" });
@@ -154,10 +208,15 @@ export default async (input: { serverUrl: URL }) => {
         },
       }),
       envoy_send: tool({
-        description: "Send an envoy agent-to-agent message to another session",
+        description:
+          "Send an Envoy agent-to-agent message directly to another session by session ID. Use this for coordination between agents or to notify a known controller/worker session. This is for SEND, not subscription.",
         args: {
-          target_session: tool.schema.string().describe("Target session ID"),
-          message: tool.schema.string().describe("Message to deliver"),
+          target_session: tool.schema
+            .string()
+            .describe("Target OpenCode session ID, e.g. ses_2e6ca3034ffejVikSZ8mDwk0mR"),
+          message: tool.schema
+            .string()
+            .describe("Message body to deliver to that session as a new user turn/notification"),
         },
         async execute(args, ctx) {
           ctx.metadata({ title: "Envoy send" });
@@ -172,6 +231,28 @@ export default async (input: { serverUrl: URL }) => {
           });
         },
       }),
+      envoy_publish: tool({
+        description:
+          "Publish an Envoy message to any topic. Use for broadcast to named topics like notifications.legion.controller, team channels, or custom routing. Subscribers matching the topic will receive the message. This is for BROADCAST, not session-targeted delivery (use envoy_send for that).",
+        args: {
+          topic: tool.schema
+            .string()
+            .describe("NATS-style topic to publish to, e.g. notifications.legion.controller"),
+          message: tool.schema.string().describe("Message body to broadcast"),
+        },
+        async execute(args, ctx) {
+          ctx.metadata({ title: "Envoy publish" });
+          return call("/v1/messages/publish", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              source_session: ctx.sessionID,
+              topic: args.topic,
+              message: args.message,
+            }),
+          });
+        },
+      }),
     },
   };
 };

package/src/port.ts

@@ -0,0 +1,34 @@
+import { execFileSync } from "node:child_process";
+
+/**
+ * Resolve the serve port from the server URL, with ss(8) fallback.
+ *
+ * Priority:
+ * 1. URL.port (standard: non-empty for non-default ports)
+ * 2. ss -tlnp PID match (finds listening port by process ID)
+ * 3. null (caller decides how to handle)
+ */
+export function resolvePort(
+  serverUrl: URL,
+  exec: typeof execFileSync = execFileSync
+): number | null {
+  // Try URL.port first (standard path for non-default ports like 4096, 13381)
+  const urlPort = Number.parseInt(serverUrl.port, 10);
+  if (Number.isFinite(urlPort) && urlPort > 0) return urlPort;
+
+  // Fallback: find listening port via ss(8) by PID
+  try {
+    const output = exec("ss", ["-tlnp"], { encoding: "utf-8" }) as string;
+    for (const line of output.split("\n")) {
+      if (!line.includes(`pid=${process.pid}`)) continue;
+      const parts = line.trim().split(/\s+/);
+      const local = parts[3];
+      const match = local?.match(/:(\d+)$/);
+      if (!match) continue;
+      const port = Number.parseInt(match[1], 10);
+      if (Number.isFinite(port) && port > 0) return port;
+    }
+  } catch {}
+
+  return null;
+}