@sjawhar/claude-envoy 0.0.0 → 1.0.0

package/src/envoy-client.ts

@@ -0,0 +1,26 @@
+import type { RequestCredential } from "@legion/envoy-client/bearer"
+import ky from "ky"
+
+export type SendEnvoyMessageOptions = {
+  readonly baseUrl: string
+  /** What the send presents (`EnabledEnvoySettings.credential`): the listener's bearer, this
+   *  machine's broker credential, which signs a DPoP proof for this request, or none, which
+   *  sends no `Authorization` header, for a loopback listener that asks for none. */
+  readonly credential: RequestCredential | undefined
+  readonly targetSession: string
+  readonly message: string
+}
+
+export async function sendEnvoyMessage(options: SendEnvoyMessageOptions): Promise<void> {
+  const url = new URL("/v1/messages/send", options.baseUrl)
+  const headers = (await options.credential?.headers("POST", url.toString())) ?? {}
+  await ky.post(url, {
+    json: {
+      target_session: options.targetSession,
+      message: options.message,
+    },
+    headers,
+    retry: 0,
+    timeout: 5_000,
+  })
+}

package/src/envoy-off.ts

@@ -0,0 +1,62 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js"
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js"
+import type { ChannelSession } from "./envoy-channel-server"
+import { roleStateFile, type SessionIdentity, writePersistedRole } from "./session-identity"
+
+/**
+ * The session of a channel server whose Envoy takes no inbound messages, for `why`: no NATS
+ * consumer, nothing registered with the listener (which would route a delivery to a deaf process),
+ * an empty inbox, and following a topic refused naming `why`. A role an explicit `envoy_role_set`
+ * claimed through the listener is still persisted, so a later server with NATS takes it back.
+ */
+export function inboundOffChannelSession(options: {
+  readonly identity: SessionIdentity
+  readonly stateDirectory: string
+  readonly why: string
+}): ChannelSession {
+  const { identity, stateDirectory, why } = options
+  return {
+    delivery: { enqueue: async () => false, inbox: () => [] },
+    topics: () => [],
+    async follow() {
+      throw new Error(`inbound messages are off for this session: ${why}`)
+    },
+    unfollow: async () => [],
+    // No heartbeat runs, so no role is ever regained.
+    onRoleRegained: () => undefined,
+    async rememberRole(role) {
+      await writePersistedRole(roleStateFile(stateDirectory, identity.id), {
+        session_id: identity.id,
+        role,
+      })
+    },
+    shutdown: async () => undefined,
+  }
+}
+
+/**
+ * The MCP server, as `serverInfo`, of a session whose Envoy is off: no tool, every call refused
+ * with `refusal`, and nothing subscribed, until stdin ends or a signal stops it.
+ */
+export async function serveEnvoyOff(
+  serverInfo: { readonly name: string; readonly version: string },
+  refusal: string,
+): Promise<void> {
+  const server = new Server(serverInfo, { capabilities: { tools: {} } })
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [] }))
+  server.setRequestHandler(CallToolRequestSchema, async () => {
+    throw new Error(refusal)
+  })
+  const stopped = Promise.withResolvers<void>()
+  process.stdin.once("end", stopped.resolve)
+  for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"] as const) {
+    process.once(signal, () => stopped.resolve())
+  }
+  await server.connect(new StdioServerTransport())
+  try {
+    await stopped.promise
+  } finally {
+    await server.close().catch(() => undefined)
+  }
+}

package/src/legion-claim.ts

@@ -0,0 +1,211 @@
+import { readdir, stat } from "node:fs/promises"
+import { join } from "node:path"
+import { setTimeout as delay } from "node:timers/promises"
+import { messageFor } from "@legion/envoy-client/errors"
+import { readSecretFile } from "@legion/envoy-client/secret-file"
+import type { EnvoyClient } from "@legion/envoy-client/transport"
+import type { LegionDaemonClient } from "@legion/pi-shared/daemon-client"
+import { bootLegionClaim } from "@legion/pi-shared/legion-claim-core"
+import type { ClaimCapability } from "@legion/pi-shared/legion-phase-ops"
+import { legion } from "../package.json" with { type: "json" }
+import { configuredValue } from "./claude-session"
+import type { ChannelSession } from "./envoy-channel-server"
+
+/**
+ * A Claude Code phase worker's claim on the Legion daemon, made by the MCP server Claude Code runs
+ * for the pane (`dist/envoy-channel.js`, under the server name `legion`) through the claim boot
+ * every harness shares (`@legion/pi-shared/legion-claim-core`). The daemon launches the pane with
+ * its boot token (`LEGION_BOOT_TOKEN_FILE`) and its address (`LEGION_DAEMON_URL`).
+ */
+
+/** What the daemon put on a Legion pane: its address, the boot token the registration spends, the
+ * claim's own Claude Code directory (`CLAUDE_CONFIG_DIR`), which holds the transcript, and whether
+ * its pod's launcher keeps that transcript in the session table (`LEGION_CLAUDE_SESSION_ID`, which
+ * only the Kubernetes runtime sets), so the registration waits for the launcher's first save. */
+export interface LegionPane {
+  readonly daemonUrl: string
+  readonly bootToken: string
+  readonly configDir: string
+  readonly launcherSaves: boolean
+}
+
+/**
+ * The Legion pane this server runs in, or undefined when no boot token is on its environment (a
+ * Claude Code session outside Legion). A set `LEGION_BOOT_TOKEN_FILE` is authoritative, as in
+ * every pane: a missing or blank file throws naming it. A pane without `LEGION_DAEMON_URL` or
+ * `CLAUDE_CONFIG_DIR` throws naming the variable.
+ */
+export function legionPane(env: NodeJS.ProcessEnv): LegionPane | undefined {
+  const pointer = env["LEGION_BOOT_TOKEN_FILE"]
+  if (pointer === undefined && configuredValue(env["LEGION_BOOT_TOKEN"]) === undefined) {
+    return undefined
+  }
+  const required = (key: string): string => {
+    const value = configuredValue(env[key])
+    if (value === undefined) {
+      throw new Error(`${key} is required for Legion: the pane carries a boot token`)
+    }
+    return value
+  }
+  return {
+    daemonUrl: required("LEGION_DAEMON_URL"),
+    configDir: required("CLAUDE_CONFIG_DIR"),
+    bootToken:
+      pointer === undefined
+        ? required("LEGION_BOOT_TOKEN")
+        : readSecretFile("LEGION_BOOT_TOKEN_FILE", pointer),
+    launcherSaves: configuredValue(env["LEGION_CLAUDE_SESSION_ID"]) !== undefined,
+  }
+}
+
+/** Writes one line to the pane's log, the server's stderr. */
+export function logLegion(line: string): void {
+  process.stderr.write(`[legion] ${line}\n`)
+}
+
+/**
+ * Ends the pane's Claude Code, this server's parent, so the daemon launches the claim again: what
+ * an Oh My Pi pane's own exit does. `legion claude-bridge` exits with Claude Code's status, and the
+ * shim reports the death.
+ */
+export function endPane(): void {
+  process.kill(process.ppid, "SIGTERM")
+}
+
+/** Logs why the pane cannot run, then ends it (`endPane`). */
+export function stopPane(why: string): void {
+  logLegion(`${why}; stopping the pane so the daemon launches it again`)
+  endPane()
+}
+
+/**
+ * The transcript Claude Code writes for `sessionID`, `<configDir>/projects/<cwd>/<id>.jsonl`, once
+ * it exists: the value a relaunch's `--resume` continues. A fresh session writes nothing until its
+ * first input, which is the bridge's `/rename` seed (`packages/daemon/internal/claudebridge`); a
+ * resumed one already has it. Polls every `pollMs` until `signal` aborts.
+ */
+export async function waitForTranscript(
+  configDir: string,
+  sessionID: string,
+  signal: AbortSignal,
+  pollMs = 100,
+): Promise<string> {
+  const projects = join(configDir, "projects")
+  const name = `${sessionID}.jsonl`
+  for (;;) {
+    signal.throwIfAborted()
+    for (const directory of await readdir(projects).catch(() => [] as string[])) {
+      const file = join(projects, directory, name)
+      if (await isFile(file)) return file
+    }
+    await delay(pollMs, undefined, { signal })
+  }
+}
+
+/** The file a pod's launcher writes beside a transcript once its first save of it has committed
+ * to the session table (`SavedMarkerSuffix`, `packages/daemon/internal/launcher/claude.go`). */
+export const SAVED_MARKER_SUFFIX = ".legion-saved"
+
+/**
+ * Waits until the pod's launcher has saved `transcript` to the session table, which it says by
+ * writing `<transcript>.legion-saved` beside it: the pod's disk dies with the pod, so a transcript
+ * the daemon recorded before the table held it would be refused at the next pod's resume. Polls
+ * every `pollMs` until `signal` aborts.
+ */
+async function waitForSavedTranscript(
+  transcript: string,
+  signal: AbortSignal,
+  pollMs = 100,
+): Promise<void> {
+  const marker = `${transcript}${SAVED_MARKER_SUFFIX}`
+  for (;;) {
+    signal.throwIfAborted()
+    if (await isFile(marker)) return
+    await delay(pollMs, undefined, { signal })
+  }
+}
+
+function isFile(file: string): Promise<boolean> {
+  return stat(file).then(
+    (info) => info.isFile(),
+    () => false,
+  )
+}
+
+export interface LegionClaim {
+  /** The registered claim, or undefined until `claims/register` has answered. */
+  readonly capability: () => ClaimCapability | undefined
+  /** Settles once the boot has run: ready sent, or the failure reported. Never rejects. */
+  readonly booted: Promise<void>
+}
+
+/**
+ * Boots the pane's claim in the background of the server (`bootLegionClaim`): waits for the
+ * transcript, and in a pod whose launcher keeps it (`launcherSaves`) for the launcher's first save
+ * of it too, registers with it as the session file (`agentId` is the session id,
+ * `pluginContract` this package's `legion.daemonApiVersion`), claims the claim token's Envoy role
+ * soft and records it with the channel session, whose heartbeat re-asserts it, and sends
+ * `claims/ready` with no capability report, again each time the heartbeat regains the role. A
+ * failure the core stops on ends the pane through `stop`; a failure before a registration is
+ * logged and leaves the pane to the daemon's registration deadline.
+ */
+export function startLegionClaim(deps: {
+  readonly pane: LegionPane
+  readonly sessionID: string
+  readonly daemon: LegionDaemonClient
+  readonly client: Pick<EnvoyClient, "setRole">
+  readonly session: Pick<ChannelSession, "rememberRole" | "onRoleRegained">
+  readonly signal: AbortSignal
+  /** Writes one line to the pane's log, the server's stderr. */
+  readonly log: (line: string) => void
+  /** Ends the pane's Claude Code, this server's parent, so the daemon launches the claim again. */
+  readonly stop: () => void
+  readonly pollMs?: number
+}): LegionClaim {
+  let capability: ClaimCapability | undefined
+  const { sessionID } = deps
+
+  const boot = async (): Promise<void> => {
+    const transcript = await waitForTranscript(
+      deps.pane.configDir,
+      sessionID,
+      deps.signal,
+      deps.pollMs,
+    )
+    if (deps.pane.launcherSaves) {
+      await waitForSavedTranscript(transcript, deps.signal, deps.pollMs)
+    }
+    await bootLegionClaim({
+      daemon: deps.daemon,
+      registration: {
+        bootToken: deps.pane.bootToken,
+        sessionId: sessionID,
+        ompSessionFile: transcript,
+        agentId: sessionID,
+        pluginContract: legion.daemonApiVersion,
+      },
+      setCapability: (registered) => {
+        capability = registered
+      },
+      claimRole: async (role) => {
+        const claimed = await deps.client.setRole({ sessionID, role, soft: true })
+        if (!claimed.claimed) {
+          throw new Error(`Envoy role ${role} is held by live session ${claimed.holder}`)
+        }
+        await deps.session.rememberRole(role)
+      },
+      onRoleRegained: (listener) => deps.session.onRoleRegained(listener),
+      log: deps.log,
+      stopping: "stopping the pane so the daemon launches it again",
+      stop: deps.stop,
+    })
+  }
+
+  const booted = boot().catch((error: unknown) => {
+    if (deps.signal.aborted) return
+    deps.log(
+      `claim boot failed before a registration; the daemon's registration deadline relaunches the pane: ${messageFor(error)}`,
+    )
+  })
+  return { capability: () => capability, booted }
+}

package/src/legion-inbox.ts

@@ -0,0 +1,110 @@
+import { randomUUID } from "node:crypto"
+import { createConnection, type Socket } from "node:net"
+import type { DeliveryCapability } from "@legion/contracts"
+import type { ChannelNotification, ChannelNotifier } from "./envoy-channel-server"
+
+/**
+ * The variable `legion claude-bridge` exports to Claude Code, and so to this server, naming its
+ * inbox socket (`packages/daemon/internal/claudebridge/inbox.go`): Claude Code's print mode never
+ * delivers a `notifications/claude/channel`, so in a Legion pane each Envoy delivery goes there and
+ * the bridge sends it to Claude Code as a user turn.
+ */
+export const INBOX_VARIABLE = "LEGION_CLAUDE_INBOX"
+
+/**
+ * The delivery modes a session whose deliveries go to the bridge's inbox advertises. The bridge
+ * (`deliver` in `packages/daemon/internal/claudebridge/bridge.go`) starts a turn with a delivery
+ * when Claude Code is idle and otherwise sends it as the next user message of the turn running,
+ * once Claude Code ends its current reply: a Send. An Aside gets the same handling, which keeps
+ * its promise: the message joins the main conversation without interrupting the work in hand.
+ * The inbox line carries no mode, since the bridge treats both alike. `btw` stays off: the bridge
+ * runs no side turn.
+ */
+export const INBOX_CAPABILITIES = [
+  "aside",
+  "steer",
+] as const satisfies readonly DeliveryCapability[]
+
+/** `InboxAnswer`: the bridge's line back for one delivery, once Claude Code took it or cannot. */
+interface InboxAnswer {
+  readonly id: string
+  readonly ok?: boolean
+  readonly error?: string
+}
+
+/**
+ * A notifier that writes each delivery to the bridge's inbox at `socketPath`, one JSON line
+ * `{id, content}` (the envelope's `event_id`, else a fresh id; the rendered content), and resolves
+ * once the bridge answers `{id, ok: true}`. The bridge answers `ok` only when Claude Code re-emits
+ * that user message (`--replay-user-messages`), that is once it took the delivery into a step, and
+ * an error when Claude Code never takes it: a relayed frame is answered `done` on the one and `nak`
+ * on the other. An answer with an error, a closed socket or an answer for another id rejects. The
+ * bridge answers one connection's lines in order, so one connection, opened on first use and again
+ * after it closes, carries every delivery.
+ */
+export function createInboxNotifier(socketPath: string): ChannelNotifier {
+  let socket: Socket | undefined
+  let buffered = ""
+  const waiting: {
+    readonly id: string
+    readonly settle: PromiseWithResolvers<void>
+  }[] = []
+
+  const fail = (error: Error): void => {
+    for (const pending of waiting.splice(0)) pending.settle.reject(error)
+  }
+
+  const answer = (line: string): void => {
+    const pending = waiting.shift()
+    if (pending === undefined) return
+    let parsed: InboxAnswer
+    try {
+      parsed = JSON.parse(line) as InboxAnswer
+    } catch {
+      pending.settle.reject(new Error(`the Legion inbox answered ${JSON.stringify(line)}`))
+      return
+    }
+    if (parsed.ok === true && parsed.id === pending.id) pending.settle.resolve()
+    else {
+      pending.settle.reject(
+        new Error(
+          `the Legion inbox refused delivery ${pending.id}: ${parsed.error ?? `answered ${line}`}`,
+        ),
+      )
+    }
+  }
+
+  const connected = (): Socket => {
+    if (socket !== undefined && !socket.destroyed) return socket
+    buffered = ""
+    const opened = createConnection(socketPath)
+    opened.setEncoding("utf8")
+    opened.on("data", (chunk: string) => {
+      buffered += chunk
+      for (let end = buffered.indexOf("\n"); end >= 0; end = buffered.indexOf("\n")) {
+        const line = buffered.slice(0, end)
+        buffered = buffered.slice(end + 1)
+        answer(line)
+      }
+    })
+    opened.on("error", (error) =>
+      fail(new Error(`the Legion inbox ${socketPath}: ${error.message}`)),
+    )
+    opened.on("close", () => {
+      fail(new Error(`the Legion inbox ${socketPath} closed before it answered`))
+      if (socket === opened) socket = undefined
+    })
+    socket = opened
+    return opened
+  }
+
+  return {
+    notification(notification: ChannelNotification): Promise<void> {
+      const id = notification.params.meta["event_id"] ?? randomUUID()
+      const settle = Promise.withResolvers<void>()
+      waiting.push({ id, settle })
+      connected().write(`${JSON.stringify({ id, content: notification.params.content })}\n`)
+      return settle.promise
+    },
+  }
+}