@sjawhar/opencode-legion-envoy 0.3.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "main": "src/server.ts",
   "exports": {
@@ -22,6 +22,8 @@
     "lint": "bunx biome check src/"
   },
   "dependencies": {
+    "@legion/contracts": "workspace:*",
+    "@legion/envoy-client": "workspace:*",
     "@opencode-ai/plugin": "~1.14.46"
   },
   "peerDependencies": {

package/src/__tests__/index.test.ts

@@ -302,96 +302,6 @@ describe("heartbeat refreshes all busy sessions (fix 1a)", () => {
   });
 });
 
-describe("re-adopts sibling sessions after serve restart (fix 1b)", () => {
-  it("registers idle same-dir+machine siblings on first activity, ignoring other machines/dirs", async () => {
-    const originalEnvoyUrl = process.env.ENVOY_URL;
-    process.env.ENVOY_URL = "http://127.0.0.1:59999";
-    const cwd = process.cwd();
-
-    const subscribed: string[] = [];
-    const originalFetch = globalThis.fetch;
-    globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
-      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
-      if (url.includes("/v1/interests/subscribe") && init?.body) {
-        const body = JSON.parse(init.body as string);
-        subscribed.push(body.session_id);
-        return new Response(JSON.stringify({ session_id: body.session_id, topics: [] }), {
-          status: 200,
-          headers: { "Content-Type": "application/json" },
-        });
-      }
-      if (url.includes("/v1/sessions")) {
-        return new Response(
-          JSON.stringify([
-            {
-              session_id: "ses_active",
-              machine_id: "M",
-              dir: cwd,
-              port: 13381,
-              title: "",
-              topics: [],
-              updated_at: Date.now(),
-            },
-            {
-              session_id: "ses_idle",
-              machine_id: "M",
-              dir: cwd,
-              port: 9,
-              title: "Idle",
-              topics: [],
-              updated_at: Date.now(),
-            },
-            {
-              session_id: "ses_foreign",
-              machine_id: "OTHER",
-              dir: cwd,
-              port: 7,
-              title: "",
-              topics: [],
-              updated_at: Date.now(),
-            },
-            {
-              session_id: "ses_otherdir",
-              machine_id: "M",
-              dir: "/somewhere/else",
-              port: 8,
-              title: "",
-              topics: [],
-              updated_at: Date.now(),
-            },
-          ]),
-          { status: 200, headers: { "Content-Type": "application/json" } }
-        );
-      }
-      if (url.includes("/session/")) return new Response("not found", { status: 404 });
-      throw new Error("connection refused");
-    }) as typeof fetch;
-
-    try {
-      const pluginModule = await import("../server");
-      const hooks = await pluginModule.default({
-        serverUrl: new URL("http://127.0.0.1:13381/"),
-      } as never);
-
-      await hooks.event({
-        event: {
-          type: "session.status",
-          properties: { sessionID: "ses_active", status: { type: "busy" } },
-        },
-      });
-      await new Promise((r) => setTimeout(r, 100));
-
-      expect(subscribed).toContain("ses_active");
-      expect(subscribed).toContain("ses_idle");
-      expect(subscribed).not.toContain("ses_foreign");
-      expect(subscribed).not.toContain("ses_otherdir");
-    } finally {
-      globalThis.fetch = originalFetch;
-      process.env.ENVOY_URL = originalEnvoyUrl;
-    }
-  });
-});
-
 describe("prunes deleted sessions from the heartbeat (fix 2)", () => {
   it("stops re-subscribing a session after session.deleted", async () => {
     const originalEnvoyUrl = process.env.ENVOY_URL;
@@ -462,88 +372,6 @@ describe("prunes deleted sessions from the heartbeat (fix 2)", () => {
   });
 });
 
-describe("re-adoption retries until the registry shows our own session (fix 3)", () => {
-  it("adopts an idle sibling once /v1/sessions includes self on a later poll", async () => {
-    const originalEnvoyUrl = process.env.ENVOY_URL;
-    const originalHb = process.env.ENVOY_HEARTBEAT_MS;
-    process.env.ENVOY_URL = "http://127.0.0.1:59999";
-    process.env.ENVOY_HEARTBEAT_MS = "40";
-    const cwd = process.cwd();
-
-    let sessionsCalls = 0;
-    const subscribed: string[] = [];
-    const originalFetch = globalThis.fetch;
-    globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
-      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
-      if (url.includes("/v1/interests/subscribe") && init?.body) {
-        const body = JSON.parse(init.body as string);
-        subscribed.push(body.session_id);
-        return new Response(JSON.stringify({ session_id: body.session_id, topics: [] }), {
-          status: 200,
-          headers: { "Content-Type": "application/json" },
-        });
-      }
-      if (url.includes("/v1/sessions")) {
-        sessionsCalls += 1;
-        // First poll: self not persisted yet. Later polls: self + idle sibling present.
-        const body =
-          sessionsCalls <= 1
-            ? []
-            : [
-                {
-                  session_id: "ses_active",
-                  machine_id: "M",
-                  dir: cwd,
-                  port: 13381,
-                  title: "",
-                  topics: [],
-                  updated_at: Date.now(),
-                },
-                {
-                  session_id: "ses_idle",
-                  machine_id: "M",
-                  dir: cwd,
-                  port: 9,
-                  title: "Idle",
-                  topics: [],
-                  updated_at: Date.now(),
-                },
-              ];
-        return new Response(JSON.stringify(body), {
-          status: 200,
-          headers: { "Content-Type": "application/json" },
-        });
-      }
-      if (url.includes("/session/")) return new Response("not found", { status: 404 });
-      throw new Error("connection refused");
-    }) as typeof fetch;
-
-    let dispose: (() => void) | undefined;
-    try {
-      const pluginModule = await import("../server");
-      const hooks = await pluginModule.default({
-        serverUrl: new URL("http://127.0.0.1:13381/"),
-      } as never);
-      dispose = (hooks as { dispose?: () => void }).dispose;
-      await hooks.event({
-        event: {
-          type: "session.status",
-          properties: { sessionID: "ses_active", status: { type: "busy" } },
-        },
-      });
-      await new Promise((r) => setTimeout(r, 200));
-
-      expect(subscribed).toContain("ses_idle");
-    } finally {
-      dispose?.();
-      globalThis.fetch = originalFetch;
-      process.env.ENVOY_URL = originalEnvoyUrl;
-      if (originalHb === undefined) delete process.env.ENVOY_HEARTBEAT_MS;
-      else process.env.ENVOY_HEARTBEAT_MS = originalHb;
-    }
-  });
-});
-
 describe("invalid ENVOY_HEARTBEAT_MS falls back to the default (fix 6)", () => {
   it("does not hammer subscribe when the env value is negative", async () => {
     const originalEnvoyUrl = process.env.ENVOY_URL;
@@ -713,72 +541,21 @@ describe("claims report whether this process drives the session", () => {
       process.env.ENVOY_URL = originalEnvoyUrl;
     }
   });
-
-  it("marks siblings re-adopted after a serve restart as not driving", async () => {
-    const originalEnvoyUrl = process.env.ENVOY_URL;
-    process.env.ENVOY_URL = "http://127.0.0.1:59999";
-
-    const claims: { id: string; driving: unknown }[] = [];
-    const originalFetch = globalThis.fetch;
-    globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
-      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
-      if (url.includes("/v1/interests/subscribe") && init?.body) {
-        const body = JSON.parse(init.body as string);
-        claims.push({ id: body.session_id, driving: body.driving });
-        return new Response(JSON.stringify({ session_id: body.session_id, topics: [] }), {
-          status: 200,
-          headers: { "Content-Type": "application/json" },
-        });
-      }
-      if (url.includes("/v1/sessions")) {
-        // A sibling session in the same dir, held by some other process.
-        return new Response(
-          JSON.stringify([
-            { session_id: "ses_sibling", machine_id: "", dir: process.cwd(), port: 34751 },
-            { session_id: "ses_driven", machine_id: "", dir: process.cwd(), port: 42145 },
-          ]),
-          { status: 200, headers: { "Content-Type": "application/json" } }
-        );
-      }
-      if (url.includes("/session/")) return new Response("not found", { status: 404 });
-      throw new Error("connection refused");
-    }) as typeof fetch;
-
-    let dispose: (() => void) | undefined;
-    try {
-      const pluginModule = await import("../server");
-      const hooks = await pluginModule.default({
-        serverUrl: new URL("http://127.0.0.1:13381/"),
-      } as never);
-      dispose = (hooks as { dispose?: () => void }).dispose;
-
-      await hooks.event({
-        event: {
-          type: "session.status",
-          properties: { sessionID: "ses_driven", status: { type: "busy" } },
-        },
-      });
-      await new Promise((r) => setTimeout(r, 60));
-
-      const sibling = claims.filter((c) => c.id === "ses_sibling");
-      expect(sibling.length).toBeGreaterThan(0);
-      expect(sibling.every((c) => c.driving !== true)).toBe(true);
-    } finally {
-      dispose?.();
-      globalThis.fetch = originalFetch;
-      process.env.ENVOY_URL = originalEnvoyUrl;
-    }
-  });
 });
 
 // Serve-restart recovery must not hijack sessions that a LIVE process still
 // serves. Because opencode session state is on shared disk and every `oc -s`
-// launch is its own process, a new process in a shared directory used to
-// re-point every sibling session's route at itself (observed: 231 sessions
-// claimed by one process in a single burst, then refreshed every 2 minutes).
-// Envoy then delivers there, and that process starts its own model loop on a
-// session another process owns — two loops, one transcript.
-describe("re-adoption only rescues sessions whose serve is gone", () => {
+// launch is its own process, a new process in a shared directory re-pointed
+// every sibling session's route at itself (observed: 231 sessions claimed by one
+// process in a single burst, then refreshed every 2 minutes). Envoy then
+// delivers there, and that process starts its own model loop on a session
+// another process owns — two loops, one transcript.
+//
+// A process may therefore claim ONLY sessions it has actually run. Keeping
+// idle-but-owned sessions reachable is the daemon's job (it knows the serve port
+// and the session IDs it dispatched), not something a stranger process may
+// arrange by adopting routes.
+describe("a process claims only sessions it has run", () => {
   const runReadopt = async (siblingPortAlive: boolean) => {
     const originalEnvoyUrl = process.env.ENVOY_URL;
     process.env.ENVOY_URL = "http://127.0.0.1:59999";
@@ -810,7 +587,7 @@ describe("re-adoption only rescues sessions whose serve is gone", () => {
           { status: 200, headers: { "Content-Type": "application/json" } }
         );
       }
-      // Liveness probe against the sibling's registered port.
+      // Any liveness probe at all means readopt is still trying to adopt.
       if (url.includes(`:${siblingPort}/`)) {
         if (siblingPortAlive) {
           return new Response(JSON.stringify({ healthy: true }), {
@@ -846,16 +623,12 @@ describe("re-adoption only rescues sessions whose serve is gone", () => {
     }
   };
 
-  it("does not adopt a sibling whose registered port is still serving", async () => {
-    const subscribed = await runReadopt(true);
+  it("never claims a sibling session, whether or not its serve is alive", async () => {
+    for (const siblingServeAlive of [true, false]) {
+      const subscribed = await runReadopt(siblingServeAlive);
 
-    expect(subscribed).toContain("ses_self");
-    expect(subscribed).not.toContain("ses_sibling");
-  });
-
-  it("adopts a sibling whose registered port is gone", async () => {
-    const subscribed = await runReadopt(false);
-
-    expect(subscribed).toContain("ses_sibling");
+      expect(subscribed).toContain("ses_self");
+      expect(subscribed).not.toContain("ses_sibling");
+    }
   });
 });

package/src/server.ts

@@ -1,3 +1,7 @@
+import { agentSubject } from "@legion/contracts";
+import { envoyDefaultsFromEnvironment } from "@legion/envoy-client/defaults";
+import { envoyToolSpecs } from "@legion/envoy-client/tool-contract";
+import { createEnvoyClient } from "@legion/envoy-client/transport";
 import { tool } from "@opencode-ai/plugin/tool";
 import { loadEnvoyConfig } from "./config";
 import { buildDispatchMcpEntry, injectEnvoyMcp } from "./dispatch-mcp";
@@ -5,24 +9,22 @@ import { dispatchSubscriptionTopic } from "./dispatch-subscribe";
 import { logger } from "./log";
 import { resolvePort } from "./port";
 
-const root = process.env.ENVOY_URL ?? "http://127.0.0.1:9020";
-
-/** HTTP timeout for Envoy calls — prevent hanging when NATS/Envoy is unavailable. */
-const CALL_TIMEOUT_MS = 5_000;
-
-async function call(path: string, init?: RequestInit) {
-  const res = await fetch(`${root}${path}`, {
-    ...init,
-    signal: init?.signal ?? AbortSignal.timeout(CALL_TIMEOUT_MS),
-  });
-  const text = await res.text();
-  if (!res.ok) throw new Error(text || `${res.status}`);
-  return text;
-}
+const [
+  subscribeSpec,
+  unsubscribeSpec,
+  listSpec,
+  sendSpec,
+  publishSpec,
+  roleSetSpec,
+  whoamiSpec,
+  sessionsSpec,
+] = envoyToolSpecs;
 
 export default async (input: { serverUrl: URL }) => {
   const cwd = process.cwd();
   const config = await loadEnvoyConfig(cwd);
+  const envoyDefaults = envoyDefaultsFromEnvironment(process.env);
+  const envoy = createEnvoyClient({ baseUrl: envoyDefaults.envoyUrl, fetch: globalThis.fetch });
   let activeSessionID: string | null = null;
   let activeSessionTitle: string | null = null;
   // All sessions that have become busy in this serve instance. The heartbeat
@@ -30,8 +32,6 @@ export default async (input: { serverUrl: URL }) => {
   // sessions, so tracking only the most-recently-active one lets idle siblings
   // expire out of the registry and become undeliverable.
   const trackedSessions = new Map<string, { title: string | null; driving: boolean }>();
-  // Guard so sibling re-adoption (after a serve restart) runs at most once.
-  let readoptDone = false;
   /** Cached port — resolved asynchronously, null until first successful resolution. */
   let resolvedPort: number | null = null;
 
@@ -63,7 +63,7 @@ export default async (input: { serverUrl: URL }) => {
   const fetchTitle = async (sessionID: string): Promise<string | null> => {
     try {
       const res = await fetch(`${input.serverUrl.href}session/${sessionID}`, {
-        signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+        signal: AbortSignal.timeout(5_000),
       });
       if (!res.ok) return null;
       const data = (await res.json()) as { title?: string };
@@ -94,98 +94,38 @@ export default async (input: { serverUrl: URL }) => {
     port: number,
     driving: boolean
   ) =>
-    call("/v1/interests/subscribe", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        session_id: sessionID,
-        dir: cwd,
-        topics: [`notifications.agent.${sessionID}`],
+    envoy
+      .subscribe({
+        sessionID,
+        directory: cwd,
+        topics: [agentSubject(sessionID)],
         port,
         title: title ?? "",
         driving,
-      }),
-    }).catch(() => {});
+      })
+      .catch(() => {});
 
-  // Does a process still answer on this port? Used to tell an orphaned session
-  // (previous serve gone: connection refused) from one a live process is still
-  // serving. Unknown port => treat as alive, i.e. do not adopt.
-  const serveAlive = async (port: number | undefined): Promise<boolean> => {
-    if (!port) return true;
-    if (port === currentPort()) return false;
-    try {
-      const controller = new AbortController();
-      const timeout = setTimeout(() => controller.abort(), 1000);
-      try {
-        await fetch(`http://127.0.0.1:${port}/global/health`, { signal: controller.signal });
-        return true;
-      } finally {
-        clearTimeout(timeout);
-      }
-    } catch {
-      return false;
-    }
-  };
-
-  // After a serve restart, sessions that were live in the previous serve instance
-  // do NOT re-register on their own (registration is gated on a session going
-  // busy), so an idle session waiting to RECEIVE a message silently falls out of
-  // the registry. Recover them once, on first activity: read the live registry and
-  // re-subscribe siblings that share this serve's machine + dir at the new port.
+  // A process registers ONLY the sessions it has actually run (see the busy
+  // handler below). It must never claim a route for a session it merely has
+  // loaded from shared on-disk state: doing so re-points that session's route
+  // here, envoy delivers here, and this process starts a second model loop on a
+  // session another process is driving.
   //
-  // Only sessions whose registered serve is GONE may be adopted. Session state
-  // lives on shared disk and every `oc -s` launch is its own process, so a
-  // same-dir sibling is usually owned by another LIVE process. Adopting those
-  // re-points their route here; envoy then delivers here, and this process
-  // starts its own model loop on a session someone else is driving — two loops
-  // interleaving one transcript. A refused connection on the registered port is
-  // the "previous serve is gone" signal this recovery was written for.
-  const readoptSiblings = async (selfSessionID: string) => {
-    if (readoptDone) return;
-    const port = currentPort();
-    if (!port) return;
-    try {
-      const res = await call("/v1/sessions");
-      const sessions = JSON.parse(res) as Array<{
-        session_id: string;
-        machine_id: string;
-        dir: string;
-        title?: string;
-        port?: number;
-      }>;
-      // Authoritative machine id for this serve = the listener-stamped machine of
-      // our own active session. Only adopt siblings that match it (and our dir) to
-      // avoid hijacking a same-path session that lives on another machine.
-      const self = sessions.find((s) => s.session_id === selfSessionID);
-      if (!self) return;
-      readoptDone = true;
-      for (const s of sessions) {
-        if (s.machine_id !== self.machine_id) continue;
-        if (s.dir !== cwd) continue;
-        if (trackedSessions.has(s.session_id)) continue;
-        if (await serveAlive(s.port)) continue;
-        trackedSessions.set(s.session_id, { title: s.title ?? null, driving: false });
-        subscribeSession(s.session_id, s.title ?? null, port, false);
-      }
-    } catch {}
-  };
+  // That means a session whose process is gone stays unreachable until it runs
+  // again. Keeping dispatched-but-idle workers reachable is the daemon's job — it
+  // knows the serve port and the session IDs it dispatched — not something a
+  // stranger process may arrange by adopting routes.
 
   // Heartbeat: re-subscribe every tracked session to refresh the envoy_sessions
   // TTL (5-min). Refreshes ALL sessions that have been busy in this serve, not
   // just the most recently active one. Interval is env-tunable for tests/tuning.
-  const rawHeartbeatMs = Number(process.env.ENVOY_HEARTBEAT_MS);
-  const heartbeatMs =
-    Number.isFinite(rawHeartbeatMs) && rawHeartbeatMs > 0
-      ? Math.max(rawHeartbeatMs, 25)
-      : 2 * 60 * 1000;
+  const heartbeatMs = envoyDefaults.heartbeatMs;
   const heartbeatInterval = setInterval(() => {
     const port = currentPort();
     if (!port) return;
     for (const [sessionID, info] of trackedSessions) {
       subscribeSession(sessionID, info.title, port, info.driving);
     }
-    // Retry sibling re-adoption until the registry shows our own session.
-    if (!readoptDone && activeSessionID) readoptSiblings(activeSessionID).catch(() => {});
   }, heartbeatMs);
   heartbeatInterval.unref?.();
 
@@ -238,9 +178,6 @@ export default async (input: { serverUrl: URL }) => {
             return t;
           });
           if (port) {
-            // Await so our own session is persisted in the registry before
-            // readoptSiblings reads it back (otherwise self may be absent and
-            // re-adoption would be skipped).
             await subscribeSession(sessionID, activeSessionTitle, port, true);
             // After the title arrives, send one follow-up subscribe with it.
             titlePromise.then((title) => {
@@ -254,9 +191,6 @@ export default async (input: { serverUrl: URL }) => {
               }
               if (activeSessionID === sessionID) activeSessionTitle = title;
             });
-            // Recover idle siblings orphaned by a serve restart (retries from the
-            // heartbeat until the registry shows our own session).
-            readoptSiblings(sessionID).catch(() => {});
           }
         }
       }
@@ -276,11 +210,7 @@ export default async (input: { serverUrl: URL }) => {
             activeSessionTitle = null;
           }
           // Best-effort: drop the deleted session's interests so routing stops.
-          call("/v1/interests/unsubscribe", {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ session_id: deletedID, topics: [] }),
-          }).catch(() => {});
+          envoy.unsubscribe({ sessionID: deletedID, topics: [] }).catch(() => {});
         }
       }
     },
@@ -295,18 +225,13 @@ export default async (input: { serverUrl: URL }) => {
       const topic = dispatchSubscriptionTopic(input.tool, output.output);
       if (!topic) return;
       try {
-        await call("/v1/interests/subscribe", {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({
-            session_id: input.sessionID,
-            dir: cwd,
-            topics: [topic],
-            port: currentPort() ?? 0,
-            title: activeSessionTitle ?? "",
-            // A tool call runs in this process, so it is the driving holder.
-            driving: true,
-          }),
+        await envoy.subscribe({
+          sessionID: input.sessionID,
+          directory: cwd,
+          topics: [topic],
+          port: currentPort() ?? 0,
+          title: activeSessionTitle ?? "",
+          driving: true,
         });
       } catch (err) {
         logger.warn(
@@ -321,132 +246,77 @@ export default async (input: { serverUrl: URL }) => {
     },
     tool: {
       envoy_subscribe: tool({
-        description:
-          "Subscribe this session to Envoy notification topics. GitHub topics are resource-scoped: notifications.github.<owner>.<repo>.pr.<number>, notifications.github.<owner>.<repo>.issue.<number>.comment, etc. Use NATS wildcards for broad subscriptions: notifications.github.<owner>.<repo>.pr.> (all PR events). Other topics: notifications.agent.<session_id>, notifications.slack.<team_id>.<channel_id>.message, 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. GitHub topics include resource number: notifications.github.owner.repo.pr.123 (PR state), notifications.github.owner.repo.pr.123.comment (PR comments), notifications.github.owner.repo.issue.456.> (all events on issue). Use > wildcard for broad matching. Other examples: notifications.agent.ses_123, notifications.slack.T09FRELLTS8.C0A0DHVU8HE.mention"
-            ),
-        },
+        description: subscribeSpec.description,
+        args: { topics: tool.schema.array(tool.schema.string()) },
         async execute(args, ctx) {
           ctx.metadata({ title: "Envoy subscribe" });
-          return call("/v1/interests/subscribe", {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
-              session_id: ctx.sessionID,
-              dir: ctx.directory,
+          return JSON.stringify(
+            await envoy.subscribe({
+              sessionID: ctx.sessionID,
+              directory: ctx.directory,
               topics: args.topics,
               port: currentPort() ?? 0,
               title: activeSessionTitle ?? "",
               driving: true,
-            }),
-          });
+            })
+          );
         },
       }),
       envoy_unsubscribe: tool({
-        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"),
-        },
+        description: unsubscribeSpec.description,
+        args: { topics: tool.schema.array(tool.schema.string()).optional() },
         async execute(args, ctx) {
           ctx.metadata({ title: "Envoy unsubscribe" });
-          return call("/v1/interests/unsubscribe", {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
-              session_id: ctx.sessionID,
-              topics: args.topics ?? [],
-            }),
-          });
+          await envoy.unsubscribe({ sessionID: ctx.sessionID, topics: args.topics ?? [] });
+          return "ok";
         },
       }),
       envoy_list: tool({
-        description:
-          "List the current Envoy topic subscriptions for this session so you can confirm the exact topic shapes that are active.",
+        description: listSpec.description,
         args: {},
         async execute(_args, ctx) {
           ctx.metadata({ title: "Envoy list" });
-          return call(`/v1/interests/${ctx.sessionID}`);
+          return JSON.stringify(await envoy.getInterest(ctx.sessionID));
         },
       }),
       envoy_send: tool({
-        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 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"),
-        },
+        description: sendSpec.description,
+        args: { target_session: tool.schema.string(), message: tool.schema.string() },
         async execute(args, ctx) {
           ctx.metadata({ title: "Envoy send" });
-          return call("/v1/messages/send", {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
-              source_session: ctx.sessionID,
-              target_session: args.target_session,
+          return JSON.stringify(
+            await envoy.send({
+              sourceSessionID: ctx.sessionID,
+              targetSessionID: args.target_session,
               message: args.message,
-            }),
-          });
+            })
+          );
         },
       }),
       envoy_publish: tool({
-        description:
-          "Publish an Envoy message to any topic. Use for broadcast to named topics like notifications.role.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.role.legion-controller"),
-          message: tool.schema.string().describe("Message body to broadcast"),
-        },
+        description: publishSpec.description,
+        args: { topic: tool.schema.string(), message: tool.schema.string() },
         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,
+          return JSON.stringify(
+            await envoy.publish({
+              sourceSessionID: ctx.sessionID,
               topic: args.topic,
               message: args.message,
-            }),
-          });
+            })
+          );
         },
       }),
       envoy_role_set: tool({
-        description:
-          "Set the current session as the holder of a named role. Messages published to notifications.role.<role> will route to this session. Only one session holds a role at a time — claiming it removes it from the previous holder.",
-        args: {
-          role: tool.schema
-            .string()
-            .describe(
-              "Role name to claim (lowercase alphanumeric, hyphens, underscores). E.g. opencode-dev, legion-controller, legion-po"
-            ),
-        },
+        description: roleSetSpec.description,
+        args: { role: tool.schema.string() },
         async execute(args, ctx) {
           ctx.metadata({ title: "Set Envoy role" });
-          return call("/v1/roles/set", {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
-              session_id: ctx.sessionID,
-              role: args.role,
-            }),
-          });
+          return JSON.stringify(await envoy.setRole({ sessionID: ctx.sessionID, role: args.role }));
         },
       }),
       envoy_whoami: tool({
-        description:
-          "Returns this session's Envoy identity: session ID, machine ID, port, and directory.",
+        description: whoamiSpec.description,
         args: {},
         async execute(_args, ctx) {
           ctx.metadata({ title: "Envoy whoami" });
@@ -465,25 +335,15 @@ export default async (input: { serverUrl: URL }) => {
         },
       }),
       envoy_sessions: tool({
-        description:
-          "List all live sessions registered with Envoy. Returns session ID, machine ID, port, directory, title, topics, and last-seen timestamp for each. Use the optional machine filter to show only sessions on a specific host.",
-        args: {
-          machine: tool.schema
-            .string()
-            .optional()
-            .describe(
-              "Filter to sessions on this machine ID (e.g. hostname). Omit to list all machines."
-            ),
-        },
+        description: sessionsSpec.description,
+        args: { machine: tool.schema.string().optional() },
         async execute(args, ctx) {
           ctx.metadata({ title: "Envoy sessions" });
-          const res = await call("/v1/sessions");
-          if (!args.machine) return res;
-          const sessions = JSON.parse(res) as Array<{
-            machine_id: string;
-          }>;
+          const sessions = await envoy.listSessions();
           return JSON.stringify(
-            sessions.filter((s) => s.machine_id === args.machine),
+            args.machine
+              ? sessions.filter((session) => session.machine_id === args.machine)
+              : sessions,
             null,
             2
           );

package/tsconfig.json

@@ -3,6 +3,13 @@
     "target": "ES2022",
     "module": "ESNext",
     "moduleResolution": "Bundler",
+    "baseUrl": ".",
+    "paths": {
+      "@legion/contracts": ["../contracts/src/index.ts"],
+      "@legion/envoy-client/defaults": ["../envoy-client/src/defaults.ts"],
+      "@legion/envoy-client/tool-contract": ["../envoy-client/src/tool-contract.ts"],
+      "@legion/envoy-client/transport": ["../envoy-client/src/transport.ts"]
+    },
     "strict": true,
     "noEmit": true,
     "skipLibCheck": true,