agent-relay-runner 0.10.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "agent-relay-runner",
+  "version": "0.10.0",
+  "description": "Unified provider lifecycle runner for Agent Relay",
+  "type": "module",
+  "bin": {
+    "claude-relay": "src/index.ts",
+    "codex-relay": "src/index.ts"
+  },
+  "files": [
+    "src/**/*.ts",
+    "plugins/**",
+    "!src/**/*.test.ts"
+  ],
+  "license": "AGPL-3.0-or-later",
+  "author": "Edin Mujkanovic <edin@exelerus.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/edimuj/agent-relay.git",
+    "directory": "runner"
+  },
+  "dependencies": {
+    "agent-relay-sdk": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/plugins/claude/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "agent-relay-runner",
+  "description": "Thin Agent Relay runner bridge for Claude Code",
+  "version": "0.10.0"
+}

package/plugins/claude/hooks/session-end.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+port="${AGENT_RELAY_RUNNER_PORT:-}"
+[ -z "$port" ] && exit 0
+curl -fsS -X POST "http://127.0.0.1:${port}/status" -H 'Content-Type: application/json' -d '{"status":"offline"}' >/dev/null || true

package/plugins/claude/hooks/stop.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+port="${AGENT_RELAY_RUNNER_PORT:-}"
+[ -z "$port" ] && exit 0
+curl -fsS -X POST "http://127.0.0.1:${port}/status" -H 'Content-Type: application/json' -d '{"status":"idle"}' >/dev/null || true

package/plugins/claude/hooks/user-prompt-submit.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+port="${AGENT_RELAY_RUNNER_PORT:-}"
+[ -z "$port" ] && exit 0
+curl -fsS -X POST "http://127.0.0.1:${port}/status" -H 'Content-Type: application/json' -d '{"status":"busy"}' >/dev/null || true

package/plugins/claude/monitors/monitors.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": "agent-relay-runner-monitor",
+    "command": "bun run \"${CLAUDE_PLUGIN_ROOT}/monitors/relay-monitor.ts\"",
+    "description": "Agent Relay runner message delivery pipe"
+  }
+]

package/plugins/claude/monitors/relay-monitor.ts

@@ -0,0 +1,30 @@
+const port = process.env.AGENT_RELAY_RUNNER_PORT;
+if (!port) process.exit(0);
+
+const ws = new WebSocket(`ws://127.0.0.1:${port}/monitor`);
+
+ws.onmessage = (event) => {
+  const payload = parsePayload(String(event.data));
+  if (!payload || payload.type !== "message.deliver" || !Array.isArray(payload.messages)) return;
+  const messages = payload.messages as Array<{ id: number; from: string; subject?: string; body: string }>;
+  for (const message of messages) {
+    const subject = message.subject ? `\nSubject: ${message.subject}` : "";
+    console.log(`Relay message #${message.id} from ${message.from}${subject}\n${message.body}`);
+  }
+  ws.send(JSON.stringify({
+    type: "message.delivered",
+    deliveryId: typeof payload.deliveryId === "string" ? payload.deliveryId : "",
+    messageIds: messages.map((message) => message.id),
+  }));
+};
+
+ws.onerror = () => process.exit(1);
+
+function parsePayload(raw: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null;
+  } catch {
+    return null;
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,69 @@
+import type { Message } from "agent-relay-sdk";
+
+export type SemanticStatus = "idle" | "busy" | "offline" | "error";
+
+export interface ProviderConfig {
+  command: string;
+  defaultArgs: string[];
+  env: Record<string, string>;
+  pluginDirs: string[];
+  defaultCapabilities: string[];
+  defaultApprovalMode: string;
+  defaultTags: string[];
+  headless: {
+    tmuxPrefix: string;
+    shutdownTimeoutMs: number;
+  };
+}
+
+export interface RunnerSpawnConfig {
+  provider: string;
+  runnerId: string;
+  instanceId: string;
+  agentId: string;
+  relayUrl: string;
+  cwd: string;
+  headless: boolean;
+  approvalMode: string;
+  label?: string;
+  prompt?: string;
+  providerArgs: string[];
+  providerConfig: ProviderConfig;
+  env: Record<string, string>;
+  controlPort: number;
+  monitor?: {
+    deliver(messages: Message[]): Promise<number[]>;
+  };
+  [key: string]: unknown;
+}
+
+export interface SpawnArgs {
+  command: string;
+  args: string[];
+  cwd: string;
+  env: Record<string, string>;
+}
+
+export interface ManagedProcess {
+  pid?: number;
+  process?: Bun.Subprocess;
+  meta?: Record<string, unknown>;
+}
+
+export interface ProviderAdapter {
+  provider: string;
+  spawn(config: RunnerSpawnConfig): Promise<ManagedProcess>;
+  shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void>;
+  deliver(process: ManagedProcess, messages: Message[]): Promise<void>;
+  onStatusChange(cb: (status: SemanticStatus) => void): void;
+  buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs;
+}
+
+export function providerMessageText(messages: Message[]): string {
+  return messages
+    .map((message) => {
+      const subject = message.subject ? `Subject: ${message.subject}\n` : "";
+      return `[relay message #${message.id} from ${message.from}]\n${subject}${message.body}`;
+    })
+    .join("\n\n");
+}

package/src/adapters/claude.ts

@@ -0,0 +1,73 @@
+import { resolve } from "node:path";
+import type { Message } from "agent-relay-sdk";
+import type { ManagedProcess, ProviderAdapter, ProviderConfig, RunnerSpawnConfig, SemanticStatus, SpawnArgs } from "../adapter";
+
+export class ClaudeAdapter implements ProviderAdapter {
+  readonly provider = "claude";
+  private statusCb: (status: SemanticStatus) => void = () => {};
+
+  onStatusChange(cb: (status: SemanticStatus) => void): void {
+    this.statusCb = cb;
+  }
+
+  async spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {
+    const args = this.buildSpawnArgs(config, config.providerConfig as ProviderConfig);
+    const proc = Bun.spawn([args.command, ...args.args], {
+      cwd: args.cwd,
+      env: args.env,
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+    });
+    void proc.exited.then((code) => this.statusCb(code === 0 ? "offline" : "error"));
+    return { pid: proc.pid, process: proc, meta: { monitor: config.monitor } };
+  }
+
+  async shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void> {
+    await terminateProcess(process, opts);
+  }
+
+  async deliver(_process: ManagedProcess, messages: Message[]): Promise<void> {
+    const monitor = _process.meta?.monitor as { deliver?(messages: Message[]): Promise<number[]> } | undefined;
+    if (!monitor?.deliver) throw new Error("Claude monitor delivery is unavailable");
+    await monitor.deliver(messages);
+  }
+
+  buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs {
+    const pluginRoot = resolve(import.meta.dir, "../../plugins/claude");
+    const pluginDirs = [...new Set([pluginRoot, ...providerConfig.pluginDirs])];
+    const args = [
+      ...pluginDirs.flatMap((dir) => ["--plugin-dir", dir]),
+      ...providerConfig.defaultArgs,
+      ...config.providerArgs,
+    ];
+    if (config.prompt) args.push(String(config.prompt));
+    return {
+      command: providerConfig.command,
+      args,
+      cwd: config.cwd,
+      env: {
+        ...config.env,
+        AGENT_RELAY_PROVIDER: "claude",
+      },
+    };
+  }
+}
+
+async function terminateProcess(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void> {
+  const proc = process.process;
+  if (!proc) return;
+  try {
+    proc.kill(opts.graceful ? "SIGTERM" : "SIGKILL");
+  } catch {
+    return;
+  }
+  const timeout = new Promise<"timeout">((resolve) => setTimeout(() => resolve("timeout"), opts.timeoutMs));
+  const result = await Promise.race([proc.exited, timeout]);
+  if (result === "timeout") {
+    try {
+      proc.kill("SIGKILL");
+    } catch {}
+    await proc.exited.catch(() => {});
+  }
+}

package/src/adapters/codex-client.ts

@@ -0,0 +1,239 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+type JsonRpcId = number | string;
+
+type JsonRpcRequest = {
+  id: JsonRpcId;
+  method: string;
+  params?: unknown;
+};
+
+type JsonRpcResponse = {
+  id: JsonRpcId;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+};
+
+type JsonRpcNotification = {
+  method: string;
+  params?: Record<string, unknown>;
+};
+
+type ThreadStatus =
+  | { type: "notLoaded" }
+  | { type: "idle" }
+  | { type: "systemError" }
+  | { type: "active"; activeFlags: string[] };
+
+type TurnStatus = "completed" | "interrupted" | "failed" | "inProgress";
+
+interface Turn {
+  id: string;
+  status: TurnStatus;
+  startedAt: number | null;
+  completedAt: number | null;
+}
+
+export interface Thread {
+  id: string;
+  cwd: string;
+  status: ThreadStatus;
+  updatedAt: number;
+  preview: string;
+  turns?: Turn[];
+}
+
+export type ClientEvent =
+  | { type: "notification"; message: JsonRpcNotification }
+  | { type: "server-request"; message: JsonRpcRequest }
+  | { type: "response"; message: JsonRpcResponse };
+
+interface TurnStartResponse {
+  turn: Turn;
+}
+
+interface ThreadStartResponse {
+  thread: Thread;
+}
+
+interface ThreadResumeResponse {
+  thread: Thread;
+}
+
+interface ThreadReadResponse {
+  thread: Thread;
+}
+
+interface ThreadListResponse {
+  data: Thread[];
+  nextCursor: string | null;
+}
+
+interface ThreadLoadedListResponse {
+  data: string[];
+  nextCursor: string | null;
+}
+
+export class CodexAppClient {
+  private ws!: WebSocket;
+  private nextId = 1;
+  private pending = new Map<JsonRpcId, { resolve: (value: any) => void; reject: (err: unknown) => void }>();
+  private events: ClientEvent[] = [];
+  private listeners = new Set<(event: ClientEvent) => void>();
+  private connected = false;
+  private connectionListeners = new Set<(connected: boolean) => void>();
+
+  constructor(private readonly url: string, private readonly log: (msg: string) => void = () => {}) {}
+
+  async connect(): Promise<void> {
+    if (this.connected) return;
+    await new Promise<void>((resolve, reject) => {
+      const ws = new WebSocket(this.url);
+      this.ws = ws;
+
+      ws.onopen = () => {
+        this.connected = true;
+        this.emitConnection(true);
+        resolve();
+      };
+      ws.onerror = (event) => reject(new Error(`websocket error: ${String((event as ErrorEvent).message || "unknown")}`));
+      ws.onclose = (event) => {
+        this.connected = false;
+        this.emitConnection(false);
+        const err = new Error(`websocket closed code=${event.code} reason=${event.reason || "(none)"}`);
+        for (const pending of this.pending.values()) pending.reject(err);
+        this.pending.clear();
+      };
+      ws.onmessage = (event) => this.handleMessage(String(event.data));
+    });
+  }
+
+  close(): void {
+    if (!this.ws) return;
+    this.ws.close();
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  async initialize(): Promise<unknown> {
+    return this.request("initialize", {
+      clientInfo: {
+        name: "agent-relay-runner-codex",
+        title: "Agent Relay Codex Runner",
+        version: "0.1.0",
+      },
+      capabilities: {
+        experimentalApi: true,
+      },
+    });
+  }
+
+  onEvent(listener: (event: ClientEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  onConnectionChange(listener: (connected: boolean) => void): () => void {
+    this.connectionListeners.add(listener);
+    return () => this.connectionListeners.delete(listener);
+  }
+
+  getEvents(): ClientEvent[] {
+    return [...this.events];
+  }
+
+  async settle(ms = 150): Promise<void> {
+    await delay(ms);
+  }
+
+  async threadStart(params: Record<string, unknown>): Promise<ThreadStartResponse> {
+    return this.request<ThreadStartResponse>("thread/start", params);
+  }
+
+  async threadResume(params: Record<string, unknown>): Promise<ThreadResumeResponse> {
+    return this.request<ThreadResumeResponse>("thread/resume", params);
+  }
+
+  async threadRead(threadId: string, includeTurns = false): Promise<ThreadReadResponse> {
+    return this.request<ThreadReadResponse>("thread/read", { threadId, includeTurns });
+  }
+
+  async threadList(params: Record<string, unknown>): Promise<ThreadListResponse> {
+    return this.request<ThreadListResponse>("thread/list", params);
+  }
+
+  async threadLoadedList(limit = 20): Promise<ThreadLoadedListResponse> {
+    return this.request<ThreadLoadedListResponse>("thread/loaded/list", { limit });
+  }
+
+  async turnStart(threadId: string, text: string): Promise<TurnStartResponse> {
+    return this.request<TurnStartResponse>("turn/start", {
+      threadId,
+      input: [{ type: "text", text }],
+    });
+  }
+
+  async turnSteer(threadId: string, turnId: string, text: string): Promise<{ turnId: string }> {
+    return this.request<{ turnId: string }>("turn/steer", {
+      threadId,
+      expectedTurnId: turnId,
+      input: [{ type: "text", text }],
+    });
+  }
+
+  async turnInterrupt(threadId: string, turnId: string): Promise<Record<string, never>> {
+    return this.request<Record<string, never>>("turn/interrupt", { threadId, turnId });
+  }
+
+  private async request<T = unknown>(method: string, params?: unknown): Promise<T> {
+    if (!this.connected) {
+      throw new Error("websocket not connected");
+    }
+    const id = this.nextId++;
+    const payload: JsonRpcRequest = { id, method, params };
+    const promise = new Promise<T>((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+    });
+    this.ws.send(JSON.stringify(payload));
+    return promise;
+  }
+
+  private handleMessage(raw: string): void {
+    const parsed = JSON.parse(raw) as JsonRpcRequest | JsonRpcResponse | JsonRpcNotification;
+
+    if ("id" in parsed && ("result" in parsed || "error" in parsed)) {
+      const pending = this.pending.get(parsed.id);
+      if (pending) {
+        this.pending.delete(parsed.id);
+        if (parsed.error) {
+          pending.reject(new Error(`${parsed.error.message} (${parsed.error.code})`));
+        } else {
+          pending.resolve(parsed.result);
+        }
+      }
+      this.record({ type: "response", message: parsed });
+      return;
+    }
+
+    if ("id" in parsed && "method" in parsed) {
+      this.log(`server-request ${parsed.method}`);
+      this.record({ type: "server-request", message: parsed });
+      return;
+    }
+
+    if ("method" in parsed) {
+      this.record({ type: "notification", message: parsed });
+    }
+  }
+
+  private record(event: ClientEvent): void {
+    this.events.push(event);
+    for (const listener of this.listeners) listener(event);
+  }
+
+  private emitConnection(connected: boolean): void {
+    for (const listener of this.connectionListeners) listener(connected);
+  }
+}

package/src/adapters/codex.ts

@@ -0,0 +1,127 @@
+import type { Message } from "agent-relay-sdk";
+import { providerMessageText, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type RunnerSpawnConfig, type SemanticStatus, type SpawnArgs } from "../adapter";
+import { CodexAppClient, type ClientEvent } from "./codex-client";
+
+export class CodexAdapter implements ProviderAdapter {
+  readonly provider = "codex";
+  private statusCb: (status: SemanticStatus) => void = () => {};
+
+  onStatusChange(cb: (status: SemanticStatus) => void): void {
+    this.statusCb = cb;
+  }
+
+  async spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {
+    const args = this.buildSpawnArgs(config, config.providerConfig as ProviderConfig);
+    const appServer = Bun.spawn([args.command, ...args.args], {
+      cwd: args.cwd,
+      env: args.env,
+      stdin: "ignore",
+      stdout: "inherit",
+      stderr: "inherit",
+    });
+    const appServerUrl = String(config.appServerUrl || args.env.CODEX_APP_SERVER_URL || "");
+    const client = appServerUrl ? new CodexAppClient(appServerUrl, () => {}) : undefined;
+    if (client) {
+      await connectWithRetry(client);
+      await client.initialize().catch(() => undefined);
+      client.onEvent((event) => this.handleCodexEvent(event));
+    }
+
+    const tui = !config.headless && config.providerConfig.command === "codex"
+      ? Bun.spawn(["codex", "--remote", appServerUrl, ...config.providerConfig.defaultArgs, ...config.providerArgs], {
+        cwd: config.cwd,
+        env: args.env,
+        stdin: "inherit",
+        stdout: "inherit",
+        stderr: "inherit",
+      })
+      : undefined;
+
+    void appServer.exited.then((code) => this.statusCb(code === 0 ? "offline" : "error"));
+    if (tui) void tui.exited.then((code) => this.statusCb(code === 0 ? "idle" : "error"));
+    return { pid: tui?.pid ?? appServer.pid, process: appServer, meta: { client, threadId: config.threadId, cwd: config.cwd, appServer, tui } };
+  }
+
+  async shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void> {
+    const client = process.meta?.client as CodexAppClient | undefined;
+    client?.close();
+    await terminateProcess(process, opts);
+  }
+
+  async deliver(process: ManagedProcess, messages: Message[]): Promise<void> {
+    const client = process.meta?.client as CodexAppClient | undefined;
+    if (!client) throw new Error("Codex App Server client is unavailable");
+    let threadId = typeof process.meta?.threadId === "string" ? process.meta.threadId : "";
+    if (!threadId) {
+      const started = await client.threadStart({ cwd: typeof process.meta?.cwd === "string" ? process.meta.cwd : globalThis.process.cwd() });
+      threadId = started.thread.id;
+      process.meta = { ...(process.meta ?? {}), threadId };
+    }
+    await client.turnStart(threadId, providerMessageText(messages));
+  }
+
+  buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs {
+    const appServerUrl = String(config.appServerUrl || process.env.CODEX_APP_SERVER_URL || `ws://127.0.0.1:${config.controlPort + 1000}`);
+    const args = providerConfig.command === "codex"
+      ? ["app-server", "--listen", appServerUrl]
+      : [...providerConfig.defaultArgs, ...config.providerArgs];
+    return {
+      command: providerConfig.command,
+      args,
+      cwd: config.cwd,
+      env: {
+        ...config.env,
+        CODEX_APP_SERVER_URL: appServerUrl,
+        AGENT_RELAY_PROVIDER: "codex",
+      },
+    };
+  }
+
+  private handleCodexEvent(event: ClientEvent): void {
+    const method = event.type === "notification" ? event.message.method : "";
+    if (method.includes("turn/started") || method.includes("turn.started")) this.statusCb("busy");
+    if (method.includes("turn/completed") || method.includes("turn.completed")) this.statusCb("idle");
+    if (method.includes("thread/status")) {
+      const params = event.type === "notification" ? event.message.params : undefined;
+      const status = params?.status;
+      if (typeof status === "string" && status.includes("active")) this.statusCb("busy");
+      if (typeof status === "string" && status.includes("idle")) this.statusCb("idle");
+    }
+  }
+}
+
+async function connectWithRetry(client: CodexAppClient, attempts = 40): Promise<void> {
+  let lastError: unknown;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      await client.connect();
+      return;
+    } catch (error) {
+      lastError = error;
+      await Bun.sleep(250);
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+
+async function terminateProcess(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void> {
+  const processes = [
+    process.meta?.tui as Bun.Subprocess | undefined,
+    process.meta?.appServer as Bun.Subprocess | undefined,
+    process.process,
+  ].filter(Boolean) as Bun.Subprocess[];
+  if (processes.length === 0) return;
+  try {
+    for (const proc of processes) proc.kill(opts.graceful ? "SIGTERM" : "SIGKILL");
+  } catch {
+    return;
+  }
+  const timeout = new Promise<"timeout">((resolve) => setTimeout(() => resolve("timeout"), opts.timeoutMs));
+  const result = await Promise.race([Promise.all(processes.map((proc) => proc.exited)), timeout]);
+  if (result === "timeout") {
+    try {
+      for (const proc of processes) proc.kill("SIGKILL");
+    } catch {}
+    await Promise.all(processes.map((proc) => proc.exited.catch(() => {})));
+  }
+}

package/src/claim-tracker.ts

@@ -0,0 +1,78 @@
+type ClaimKind = "message" | "task" | "command";
+type RunnerBusyReason = "provider-turn" | ClaimKind;
+type RunnerSemanticStatus = "idle" | "busy" | "offline" | "error";
+
+interface ClaimRecord {
+  id: string;
+  kind: ClaimKind;
+  startedAt: number;
+  expiresAt?: number;
+}
+
+export class ClaimTracker {
+  private providerBusy = false;
+  private status: RunnerSemanticStatus = "idle";
+  private readonly claims = new Map<string, ClaimRecord>();
+
+  setProviderBusy(busy: boolean): boolean {
+    const before = this.currentStatus();
+    this.providerBusy = busy;
+    return before !== this.currentStatus();
+  }
+
+  setTerminalStatus(status: "offline" | "error"): boolean {
+    const before = this.status;
+    this.status = status;
+    return before !== status;
+  }
+
+  clearTerminalStatus(): boolean {
+    const before = this.status;
+    this.status = "idle";
+    return before !== this.status;
+  }
+
+  startClaim(kind: ClaimKind, id: string, expiresAt?: number): boolean {
+    const before = this.currentStatus();
+    this.claims.set(`${kind}:${id}`, { kind, id, startedAt: Date.now(), expiresAt });
+    return before !== this.currentStatus();
+  }
+
+  finishClaim(kind: ClaimKind, id: string): boolean {
+    const before = this.currentStatus();
+    this.claims.delete(`${kind}:${id}`);
+    return before !== this.currentStatus();
+  }
+
+  clearKind(kind: ClaimKind): boolean {
+    const before = this.currentStatus();
+    for (const key of [...this.claims.keys()]) {
+      if (key.startsWith(`${kind}:`)) this.claims.delete(key);
+    }
+    return before !== this.currentStatus();
+  }
+
+  expire(now = Date.now()): boolean {
+    const before = this.currentStatus();
+    for (const [key, claim] of this.claims) {
+      if (claim.expiresAt !== undefined && claim.expiresAt <= now) this.claims.delete(key);
+    }
+    return before !== this.currentStatus();
+  }
+
+  currentStatus(): RunnerSemanticStatus {
+    if (this.status === "offline" || this.status === "error") return this.status;
+    return this.providerBusy || this.claims.size > 0 ? "busy" : "idle";
+  }
+
+  reasons(): RunnerBusyReason[] {
+    const reasons = new Set<RunnerBusyReason>();
+    if (this.providerBusy) reasons.add("provider-turn");
+    for (const claim of this.claims.values()) reasons.add(claim.kind);
+    return [...reasons];
+  }
+
+  activeClaims(): ClaimRecord[] {
+    return [...this.claims.values()];
+  }
+}

package/src/config.ts

@@ -0,0 +1,144 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { join, resolve } from "node:path";
+import type { ProviderConfig } from "./adapter";
+
+interface GlobalRunnerConfig {
+  relayUrl: string;
+  token?: string;
+  defaultCwd: string;
+}
+
+interface LoadedProviderConfig extends ProviderConfig {
+  path: string;
+}
+
+const DEFAULT_RELAY_URL = "http://127.0.0.1:4850";
+
+function agentRelayHome(): string {
+  return process.env.AGENT_RELAY_HOME || join(homedir(), ".agent-relay");
+}
+
+function providersDir(home = agentRelayHome()): string {
+  return join(home, "providers");
+}
+
+export function defaultProviderConfig(provider: string): ProviderConfig {
+  const command = provider === "claude" ? "claude-rig" : provider;
+  return {
+    command,
+    defaultArgs: provider === "claude" ? ["--dangerously-skip-permissions"] : [],
+    env: {},
+    pluginDirs: [],
+    defaultCapabilities: ["chat", "code", "review"],
+    defaultApprovalMode: "guarded",
+    defaultTags: [],
+    headless: {
+      tmuxPrefix: `${provider}-relay`,
+      shutdownTimeoutMs: 10_000,
+    },
+  };
+}
+
+export function loadGlobalConfig(home = agentRelayHome()): GlobalRunnerConfig {
+  const path = join(home, "config.json");
+  const parsed = readJson(path);
+  return {
+    relayUrl: stringValue(parsed.relayUrl) ?? process.env.AGENT_RELAY_URL ?? DEFAULT_RELAY_URL,
+    token: stringValue(parsed.token) ?? process.env.AGENT_RELAY_TOKEN,
+    defaultCwd: stringValue(parsed.defaultCwd) ?? process.cwd(),
+  };
+}
+
+export function loadProviderConfig(provider: string, home = agentRelayHome()): LoadedProviderConfig {
+  const path = join(providersDir(home), `${provider}.json`);
+  const raw = readJson(path);
+  const defaults = defaultProviderConfig(provider);
+  return {
+    path,
+    command: stringValue(raw.command) ?? defaults.command,
+    defaultArgs: stringArray(raw.defaultArgs) ?? defaults.defaultArgs,
+    env: stringRecord(raw.env) ?? defaults.env,
+    pluginDirs: stringArray(raw.pluginDirs) ?? defaults.pluginDirs,
+    defaultCapabilities: stringArray(raw.defaultCapabilities) ?? defaults.defaultCapabilities,
+    defaultApprovalMode: stringValue(raw.defaultApprovalMode) ?? defaults.defaultApprovalMode,
+    defaultTags: stringArray(raw.defaultTags) ?? defaults.defaultTags,
+    headless: {
+      tmuxPrefix: stringValue(recordValue(raw.headless).tmuxPrefix) ?? defaults.headless.tmuxPrefix,
+      shutdownTimeoutMs: positiveInteger(recordValue(raw.headless).shutdownTimeoutMs) ?? defaults.headless.shutdownTimeoutMs,
+    },
+  };
+}
+
+export function writeProviderConfig(provider: string, config: ProviderConfig, home = agentRelayHome()): LoadedProviderConfig {
+  const dir = providersDir(home);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${provider}.json`);
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  return { ...config, path };
+}
+
+export function providerConfigPublic(config: LoadedProviderConfig): Record<string, unknown> {
+  return {
+    path: config.path,
+    command: config.command,
+    defaultArgs: config.defaultArgs,
+    env: maskEnv(config.env),
+    pluginDirs: config.pluginDirs,
+    defaultCapabilities: config.defaultCapabilities,
+    defaultApprovalMode: config.defaultApprovalMode,
+    defaultTags: config.defaultTags,
+    headless: config.headless,
+  };
+}
+
+export function runnerId(provider: string, cwd: string, label?: string): string {
+  const project = cwd.split("/").filter(Boolean).at(-1) || "workspace";
+  const cleanLabel = (label || project).replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase();
+  return `${hostname()}-${provider}-${cleanLabel}-${crypto.randomUUID().slice(0, 8)}`;
+}
+
+export function resolveCwd(value: string | undefined, fallback: string): string {
+  return resolve(value || fallback);
+}
+
+function readJson(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : {};
+  } catch {
+    return {};
+  }
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function positiveInteger(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+function stringArray(value: unknown): string[] | undefined {
+  return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : undefined;
+}
+
+function stringRecord(value: unknown): Record<string, string> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const entries = Object.entries(value);
+  if (entries.some(([, item]) => typeof item !== "string")) return undefined;
+  return Object.fromEntries(entries) as Record<string, string>;
+}
+
+function recordValue(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function maskEnv(env: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    result[key] = /token|secret|key|password/i.test(key) && !value.startsWith("$env:") ? "********" : value;
+  }
+  return result;
+}

package/src/control-server.ts

@@ -0,0 +1,109 @@
+import type { Server, ServerWebSocket } from "bun";
+import type { Message } from "agent-relay-sdk";
+import type { SemanticStatus } from "./adapter";
+
+interface MonitorSocketData {
+  kind: "monitor";
+}
+
+type MonitorSocket = ServerWebSocket<MonitorSocketData>;
+
+export interface ControlServer {
+  port: number;
+  url: string;
+  stop(): void;
+  deliverToMonitor(messages: Message[], timeoutMs?: number): Promise<number[]>;
+}
+
+interface ControlServerOptions {
+  onStatus(status: SemanticStatus): void;
+}
+
+export function startControlServer(options: ControlServerOptions): ControlServer {
+  const monitors = new Set<MonitorSocket>();
+  const pendingDeliveries = new Map<string, { resolve(ids: number[]): void; timer: Timer }>();
+  let server!: Server<MonitorSocketData>;
+
+  server = Bun.serve<MonitorSocketData>({
+    hostname: "127.0.0.1",
+    port: 0,
+    fetch(req, srv) {
+      const url = new URL(req.url);
+      if (url.pathname === "/health") return Response.json({ ok: true });
+      if (url.pathname === "/status" && req.method === "GET") return Response.json({ ok: true });
+      if (url.pathname === "/status" && req.method === "POST") {
+        return handleStatus(req, options);
+      }
+      if (url.pathname === "/monitor") {
+        const upgraded = srv.upgrade(req, { data: { kind: "monitor" } });
+        return upgraded ? undefined : new Response("WebSocket upgrade failed", { status: 400 });
+      }
+      return new Response("not found", { status: 404 });
+    },
+    websocket: {
+      open(ws) {
+        monitors.add(ws);
+      },
+      message(_ws, raw) {
+        const parsed = parseJson(raw);
+        if (parsed?.type === "message.delivered" && Array.isArray(parsed.messageIds)) {
+          const deliveryId = typeof parsed.deliveryId === "string" ? parsed.deliveryId : "";
+          const pending = pendingDeliveries.get(deliveryId);
+          if (pending) {
+            clearTimeout(pending.timer);
+            pendingDeliveries.delete(deliveryId);
+            pending.resolve(parsed.messageIds.filter((id): id is number => Number.isSafeInteger(id)));
+          }
+        }
+      },
+      close(ws) {
+        monitors.delete(ws);
+      },
+    },
+  });
+
+  const port = server.port;
+  if (port === undefined) throw new Error("runner control server did not bind a port");
+
+  return {
+    port,
+    url: `http://127.0.0.1:${port}`,
+    stop() {
+      for (const pending of pendingDeliveries.values()) clearTimeout(pending.timer);
+      pendingDeliveries.clear();
+      server.stop(true);
+    },
+    async deliverToMonitor(messages: Message[], timeoutMs = 30_000): Promise<number[]> {
+      if (monitors.size === 0) throw new Error("no Claude monitor connected");
+      const deliveryId = crypto.randomUUID();
+      const payload = JSON.stringify({ type: "message.deliver", deliveryId, messages });
+      return await new Promise<number[]>((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pendingDeliveries.delete(deliveryId);
+          reject(new Error("monitor delivery timed out"));
+        }, timeoutMs);
+        pendingDeliveries.set(deliveryId, { resolve, timer });
+        for (const monitor of monitors) monitor.send(payload);
+      });
+    },
+  };
+}
+
+async function handleStatus(req: Request, options: ControlServerOptions): Promise<Response> {
+  const body = await req.json().catch(() => null) as { status?: unknown } | null;
+  const status = body?.status;
+  if (status !== "idle" && status !== "busy" && status !== "offline" && status !== "error") {
+    return Response.json({ error: "status must be idle, busy, offline, or error" }, { status: 400 });
+  }
+  options.onStatus(status);
+  return Response.json({ ok: true, status });
+}
+
+function parseJson(raw: string | Buffer): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(typeof raw === "string" ? raw : raw.toString());
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null;
+  } catch {
+    return null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,105 @@
+#!/usr/bin/env bun
+import { basename } from "node:path";
+import { ClaudeAdapter } from "./adapters/claude";
+import { CodexAdapter } from "./adapters/codex";
+import { AgentRunner } from "./runner";
+import { loadGlobalConfig, loadProviderConfig, resolveCwd, runnerId } from "./config";
+
+interface CliOptions {
+  provider: "claude" | "codex";
+  headless: boolean;
+  cwd?: string;
+  relayUrl?: string;
+  token?: string;
+  approvalMode?: string;
+  label?: string;
+  agentId?: string;
+  prompt?: string;
+  providerArgs: string[];
+}
+
+export async function main(argv = process.argv): Promise<void> {
+  const opts = parseArgs(argv);
+  const globalConfig = loadGlobalConfig();
+  const providerConfig = loadProviderConfig(opts.provider);
+  const cwd = resolveCwd(opts.cwd, globalConfig.defaultCwd);
+  const id = runnerId(opts.provider, cwd, opts.label);
+  const adapter = opts.provider === "claude" ? new ClaudeAdapter() : new CodexAdapter();
+  const runner = new AgentRunner({
+    provider: opts.provider,
+    runnerId: id,
+    instanceId: crypto.randomUUID(),
+    agentId: opts.agentId,
+    relayUrl: opts.relayUrl ?? globalConfig.relayUrl,
+    token: opts.token ?? globalConfig.token,
+    cwd,
+    headless: opts.headless,
+    approvalMode: opts.approvalMode ?? providerConfig.defaultApprovalMode,
+    label: opts.label,
+    prompt: opts.prompt,
+    providerArgs: opts.providerArgs,
+    providerConfig,
+    adapter,
+  });
+  await runner.run();
+  await waitForShutdown(() => runner.stop());
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  const bin = basename(argv[1] || "");
+  let provider: "claude" | "codex" = bin.includes("claude") ? "claude" : "codex";
+  const relayArgs = argv.slice(2);
+  const providerSep = relayArgs.indexOf("--");
+  const ownArgs = providerSep >= 0 ? relayArgs.slice(0, providerSep) : relayArgs;
+  const providerArgs = providerSep >= 0 ? relayArgs.slice(providerSep + 1) : [];
+  let headless = false;
+  let cwd: string | undefined;
+  let relayUrl: string | undefined;
+  let token: string | undefined;
+  let approvalMode: string | undefined;
+  let label: string | undefined;
+  let agentId: string | undefined;
+  let prompt: string | undefined;
+
+  for (let i = 0; i < ownArgs.length; i++) {
+    const arg = ownArgs[i];
+    if (arg === "claude" || arg === "codex") provider = arg;
+    else if (arg === "--headless") headless = true;
+    else if (arg === "--cwd" && ownArgs[i + 1]) cwd = ownArgs[++i];
+    else if (arg === "--relay-url" && ownArgs[i + 1]) relayUrl = ownArgs[++i];
+    else if (arg === "--token" && ownArgs[i + 1]) token = ownArgs[++i];
+    else if ((arg === "--approval" || arg === "--approval-mode") && ownArgs[i + 1]) approvalMode = ownArgs[++i];
+    else if (arg === "--label" && ownArgs[i + 1]) label = ownArgs[++i];
+    else if (arg === "--agent-id" && ownArgs[i + 1]) agentId = ownArgs[++i];
+    else if (arg === "--prompt" && ownArgs[i + 1]) prompt = ownArgs[++i];
+    else if (arg === "--help" || arg === "-h") {
+      printHelp(provider);
+      process.exit(0);
+    } else {
+      providerArgs.push(arg!);
+    }
+  }
+
+  return { provider, headless, cwd, relayUrl, token, approvalMode, label, agentId, prompt, providerArgs };
+}
+
+function printHelp(provider: string): void {
+  console.log(`${provider}-relay [--headless] [--cwd PATH] [--relay-url URL] [--approval MODE] [--label NAME] [--agent-id ID] [-- provider-args...]`);
+}
+
+async function waitForShutdown(stop: () => Promise<void>): Promise<void> {
+  let stopping = false;
+  const shutdown = async () => {
+    if (stopping) return;
+    stopping = true;
+    await stop();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown());
+  process.on("SIGTERM", () => void shutdown());
+  await new Promise(() => {});
+}
+
+if (import.meta.main) {
+  await main();
+}

package/src/runner.ts

@@ -0,0 +1,274 @@
+import { hostname } from "node:os";
+import type { Message } from "agent-relay-sdk";
+import { RelayBusClient, RelayHttpClient } from "agent-relay-sdk";
+import type { ManagedProcess, ProviderAdapter, ProviderConfig, RunnerSpawnConfig, SemanticStatus } from "./adapter";
+import { ClaimTracker } from "./claim-tracker";
+import { startControlServer, type ControlServer } from "./control-server";
+
+interface RunnerOptions {
+  provider: string;
+  runnerId: string;
+  instanceId: string;
+  agentId?: string;
+  relayUrl: string;
+  token?: string;
+  cwd: string;
+  headless: boolean;
+  approvalMode: string;
+  label?: string;
+  prompt?: string;
+  providerArgs: string[];
+  providerConfig: ProviderConfig;
+  adapter: ProviderAdapter;
+}
+
+export class AgentRunner {
+  private readonly agentId: string;
+  private readonly claims = new ClaimTracker();
+  private readonly http: RelayHttpClient;
+  private readonly bus: RelayBusClient;
+  private control?: ControlServer;
+  private process?: ManagedProcess;
+  private stopped = false;
+  private delivering = false;
+  private readonly pendingMessages = new Map<number, Message>();
+
+  constructor(private readonly options: RunnerOptions) {
+    this.agentId = options.agentId ?? options.runnerId;
+    this.http = new RelayHttpClient({ baseUrl: options.relayUrl, token: options.token });
+    this.bus = new RelayBusClient({
+      url: relayBusUrl(options.relayUrl),
+      role: "provider",
+      componentId: options.runnerId,
+      agentId: this.agentId,
+      instanceId: options.instanceId,
+      token: options.token,
+      machine: hostname(),
+      capabilities: [
+        ...new Set([
+          ...options.providerConfig.defaultCapabilities,
+          "lifecycle.shutdown.hard",
+          "lifecycle.restart.hard",
+          "lifecycle.status.semantic",
+          "lifecycle.heartbeat",
+          "lifecycle.reconnect.transport",
+          "commands.lifecycle",
+          "capabilities.report",
+        ]),
+      ],
+      tags: [...new Set([options.provider, ...csvTags(process.env.AGENT_RELAY_TAGS), ...options.providerConfig.defaultTags, ...(options.headless ? ["headless"] : [])])],
+      meta: {
+        provider: options.provider,
+        runnerId: options.runnerId,
+        runnerManaged: true,
+        cwd: options.cwd,
+        approvalMode: options.approvalMode,
+        label: options.label ?? null,
+        lifecycleCapabilities: lifecycleCapabilities(),
+      },
+      heartbeatIntervalMs: 30_000,
+      initialStatus: "idle",
+    });
+  }
+
+  get id(): string {
+    return this.agentId;
+  }
+
+  async run(): Promise<void> {
+    this.control = startControlServer({ onStatus: (status) => this.setProviderStatus(status) });
+    this.options.adapter.onStatusChange((status) => this.setProviderStatus(status));
+    this.bus.on("message.new", (message) => this.enqueueMessage(message as Message));
+    this.bus.on("command", (type, params, commandId, command) => {
+      void this.handleCommand(type, params, commandId, command);
+    });
+    await this.bus.connect();
+    this.process = await this.spawnProvider();
+    this.publishStatus();
+  }
+
+  async stop(): Promise<void> {
+    this.stopped = true;
+    await this.bus.statusAsync({ agentStatus: "offline", ready: false });
+    if (this.process) {
+      await this.options.adapter.shutdown(this.process, {
+        graceful: true,
+        timeoutMs: this.options.providerConfig.headless.shutdownTimeoutMs,
+      });
+    }
+    this.control?.stop();
+    await this.bus.close();
+  }
+
+  private async spawnProvider(): Promise<ManagedProcess> {
+    const env = {
+      ...process.env as Record<string, string>,
+      ...this.options.providerConfig.env,
+      AGENT_RELAY_RUNNER_PORT: String(this.control!.port),
+      AGENT_RELAY_RUNNER_ID: this.options.runnerId,
+      AGENT_RELAY_ID: this.agentId,
+      AGENT_RELAY_URL: this.options.relayUrl,
+      AGENT_RELAY_APPROVAL: this.options.approvalMode,
+      ...(this.options.token ? { AGENT_RELAY_TOKEN: this.options.token } : {}),
+    };
+    const config: RunnerSpawnConfig = {
+      provider: this.options.provider,
+      runnerId: this.options.runnerId,
+      instanceId: this.options.instanceId,
+      agentId: this.agentId,
+      relayUrl: this.options.relayUrl,
+      cwd: this.options.cwd,
+      headless: this.options.headless,
+      approvalMode: this.options.approvalMode,
+      ...(this.options.label ? { label: this.options.label } : {}),
+      ...(this.options.prompt ? { prompt: this.options.prompt } : {}),
+      providerArgs: this.options.providerArgs,
+      providerConfig: this.options.providerConfig,
+      env,
+      controlPort: this.control!.port,
+      monitor: {
+        deliver: (messages) => this.control!.deliverToMonitor(messages),
+      },
+    };
+    return this.options.adapter.spawn(config);
+  }
+
+  private enqueueMessage(message: Message): void {
+    if (!this.matchesMessage(message)) return;
+    this.pendingMessages.set(message.id, message);
+    void this.drainMessages();
+  }
+
+  private async drainMessages(): Promise<void> {
+    if (this.delivering || this.pendingMessages.size === 0 || !this.process) return;
+    this.delivering = true;
+    const messages = [...this.pendingMessages.values()].sort((a, b) => a.id - b.id);
+    this.pendingMessages.clear();
+    for (const message of messages) {
+      if (message.claimable) {
+        const claimed = await this.http.claimMessage(message.id, this.agentId).catch(() => false);
+        if (!claimed) continue;
+        this.claims.startClaim("message", String(message.id), message.claimExpiresAt);
+      }
+    }
+    this.publishStatus();
+    try {
+      await this.options.adapter.deliver(this.process, messages);
+      for (const message of messages) {
+        await this.http.markRead(message.id, this.agentId).catch(() => {});
+        this.claims.finishClaim("message", String(message.id));
+      }
+    } finally {
+      this.delivering = false;
+      this.publishStatus();
+      if (this.pendingMessages.size > 0) void this.drainMessages();
+    }
+  }
+
+  private async handleCommand(type: string, params: Record<string, unknown>, commandId: string, command?: Record<string, unknown>): Promise<void> {
+    const target = typeof command?.target === "string" ? command.target : this.agentId;
+    if (target !== this.agentId && target !== this.options.runnerId) return;
+    if (type !== "agent.shutdown" && type !== "agent.restart" && type !== "agent.kill") return;
+
+    this.claims.startClaim("command", commandId);
+    this.publishStatus();
+    await this.updateCommand(commandId, "accepted");
+    await this.updateCommand(commandId, "running");
+    try {
+      if (type === "agent.restart") await this.restartProvider();
+      else await this.shutdownProvider(type === "agent.kill");
+      await this.updateCommand(commandId, "succeeded", { action: type, agentId: this.agentId, runnerId: this.options.runnerId });
+      if (type !== "agent.restart") setTimeout(() => void this.stop().finally(() => process.exit(0)), 10);
+    } catch (error) {
+      await this.updateCommand(commandId, "failed", undefined, error instanceof Error ? error.message : String(error));
+    } finally {
+      this.claims.finishClaim("command", commandId);
+      this.publishStatus();
+    }
+  }
+
+  private async restartProvider(): Promise<void> {
+    if (this.process) {
+      await this.options.adapter.shutdown(this.process, {
+        graceful: true,
+        timeoutMs: this.options.providerConfig.headless.shutdownTimeoutMs,
+      });
+    }
+    if (this.stopped) return;
+    this.process = await this.spawnProvider();
+  }
+
+  private async shutdownProvider(hard: boolean): Promise<void> {
+    await this.bus.statusAsync({ agentStatus: "idle", ready: false });
+    if (this.process) {
+      await this.options.adapter.shutdown(this.process, {
+        graceful: !hard,
+        timeoutMs: this.options.providerConfig.headless.shutdownTimeoutMs,
+      });
+    }
+    this.claims.setTerminalStatus("offline");
+    this.publishStatus();
+    await this.http.deleteAgent(this.agentId).catch(() => {});
+    this.stopped = true;
+  }
+
+  private async updateCommand(commandId: string, status: string, result?: Record<string, unknown>, error?: string): Promise<void> {
+    await this.bus.updateCommand(commandId, { status, ...(result ? { result } : {}), ...(error ? { error } : {}) });
+  }
+
+  private setProviderStatus(status: SemanticStatus): void {
+    if (status === "busy") this.claims.setProviderBusy(true);
+    else if (status === "idle") this.claims.setProviderBusy(false);
+    else if (status === "offline" || status === "error") this.claims.setTerminalStatus(status);
+    this.publishStatus();
+  }
+
+  private publishStatus(): void {
+    const status = this.claims.currentStatus();
+    this.bus.setSemanticStatus(status === "offline" || status === "error" ? "idle" : status);
+    this.bus.status({
+      agentStatus: status,
+      ready: status !== "offline" && !this.stopped,
+      meta: {
+        runnerId: this.options.runnerId,
+        busyReasons: this.claims.reasons(),
+        transport: this.bus.transportState,
+      },
+    });
+  }
+
+  private matchesMessage(message: Message): boolean {
+    if (message.to === this.agentId || message.to === "broadcast") return true;
+    if (message.to === `label:${this.options.label}`) return true;
+    if (message.to.startsWith("tag:")) {
+      const tag = message.to.slice("tag:".length);
+      return this.options.providerConfig.defaultTags.includes(tag) || tag === this.options.provider;
+    }
+    if (message.to.startsWith("cap:")) {
+      const cap = message.to.slice("cap:".length);
+      return this.options.providerConfig.defaultCapabilities.includes(cap);
+    }
+    return false;
+  }
+}
+
+function csvTags(raw: string | undefined): string[] {
+  return (raw || "").split(",").map((tag) => tag.trim()).filter(Boolean);
+}
+
+function relayBusUrl(relayUrl: string): string {
+  const url = new URL(relayUrl);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  url.pathname = `${url.pathname.replace(/\/+$/, "")}/bus`;
+  url.search = "";
+  return url.toString();
+}
+
+function lifecycleCapabilities(): Record<string, true> {
+  return {
+    shutdownHard: true,
+    restartHard: true,
+    semanticStatus: true,
+    transportReconnect: true,
+  };
+}