agent-relay-server 0.4.37 → 0.4.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.4.37",
+  "version": "0.4.39",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",

package/public/dashboard.js

@@ -6,6 +6,7 @@
   const DEFAULT_INBOX_COMPOSE = { toMode: "agent", to: "", body: "", channel: "", subject: "", claimable: false };
   const DEFAULT_PAIR_MESSAGE = { pairId: "", from: "", body: "", subject: "" };
   const DEFAULT_PAIR_INVITE = { requesterId: "", targetId: "", objective: "" };
+  const DEFAULT_AGENT_SPAWN = { provider: "codex", approvalMode: "guarded", cwd: "", label: "" };
   const CLOSED_TASK_STATUSES = new Set(["done", "failed", "canceled"]);
   const WAITING_TASK_STATUSES = new Set(["open", "blocked"]);
   const STATUS_SORT_ORDER = { online: 0, idle: 1, busy: 2, offline: 3 };
@@ -15,6 +16,7 @@
     claude: "claude-sol",
     user: "ti-user",
     system: "ti-server",
+    channel: "ti-messages",
     agent: "ti-robot",
   };
   const AGENT_TYPE_TITLES = {
@@ -22,6 +24,7 @@
     claude: "Claude agent",
     user: "Human operator",
     system: "System",
+    channel: "Channel",
     agent: "Agent",
   };
 
@@ -76,9 +79,13 @@
       selectedAgent: "",
       agentDetailOpen: false,
       agentDetailId: "",
+      channelDetailOpen: false,
+      channelDetailId: "",
       selectedInboxThread: "",
       replyTo: null,
       composeOpen: false,
+      agentSpawnOpen: false,
+      agentDirectoryBrowser: { open: false, loading: false, path: "", parent: "", home: "", cwd: "", entries: [], error: "" },
       pairInviteOpen: false,
       pairMessageOpen: false,
       threadOpen: false,
@@ -90,6 +97,7 @@
       authNeeded: false,
 
       compose: { ...DEFAULT_COMPOSE },
+      agentSpawn: { ...DEFAULT_AGENT_SPAWN },
       pairInvite: { ...DEFAULT_PAIR_INVITE },
       pairMessage: { ...DEFAULT_PAIR_MESSAGE },
       inboxCompose: { ...DEFAULT_INBOX_COMPOSE },
@@ -496,11 +504,14 @@
   function createComputedDescriptors() {
     return {
       onlineCount: { get: getOnlineCount },
+      busyAgentCount: { get: getBusyAgentCount },
       hiddenBuiltInAgentCount: { get: getHiddenBuiltInAgentCount },
       sortedAgents: { get: getSortedAgents },
       pairsByAgentId: { get: getPairsByAgentId },
       selectedAgentDetail: { get: getSelectedAgentDetail },
       agentDetailMessages: { get: getAgentDetailMessages },
+      selectedChannelDetail: { get: getSelectedChannelDetail },
+      channelDetailMessages: { get: getChannelDetailMessages },
       pairMessagePair: { get: getPairMessagePair },
       allInboxThreads: { get: getAllInboxThreads },
       inboxThreads: { get: getInboxThreads },
@@ -513,6 +524,7 @@
       workQueueItems: { get: getWorkQueueItems },
       channelCards: { get: getChannelCards },
       integrationCards: { get: getIntegrationCards },
+      openPairCount: { get: getOpenPairCount },
       filteredMessages: { get: getFilteredMessages },
       groupedMessages: { get: getGroupedMessages },
       filteredTasks: { get: getFilteredTasks },
@@ -530,6 +542,10 @@
     return visibleAgents(this).filter((agent) => agent.status !== "offline").length;
   }
 
+  function getBusyAgentCount() {
+    return this.agents.filter((agent) => agent.status === "busy").length;
+  }
+
   function getHiddenBuiltInAgentCount() {
     return this.showBuiltIns ? 0 : this.agents.filter(isBuiltInAgent).length;
   }
@@ -578,6 +594,29 @@
       .slice(0, 8);
   }
 
+  function getSelectedChannelDetail() {
+    if (!this.channelDetailId) return null;
+    return (this.channels || []).find((channel) => channel.id === this.channelDetailId) || null;
+  }
+
+  function getChannelDetailMessages() {
+    const channel = this.selectedChannelDetail;
+    if (!channel) return [];
+    return this.messages
+      .filter((msg) => messageMatchesChannel(msg, channel))
+      .slice()
+      .sort((a, b) => b.id - a.id)
+      .slice(0, 8);
+  }
+
+  function messageMatchesChannel(message, channel) {
+    if (!message || !channel) return false;
+    const channelKeys = [channel.id, channel.type, ...(channel.topicChannels || [])].filter(Boolean);
+    if (message.channel && channelKeys.includes(message.channel)) return true;
+    if (channel.agentId && (message.from === channel.agentId || message.to === channel.agentId)) return true;
+    return false;
+  }
+
   function getPairMessagePair() {
     return this.pairs.find((pair) => pair.id === this.pairMessage.pairId) || null;
   }
@@ -1071,11 +1110,47 @@
     });
   }
 
+  function getOpenPairCount() {
+    return (this.pairs || []).filter(isOpenPair).length;
+  }
+
+  function isOpenPair(pair) {
+    return pair?.status === "active" || pair?.status === "pending";
+  }
+
   function getComposeAgents() {
     const list = visibleAgents(this);
     return this.showOffline ? list : list.filter((agent) => agent.status !== "offline");
   }
 
+  function composeTargetAllowsClaimable() {
+    return matchingComposeRecipientCount(this, this.compose.to) > 1;
+  }
+
+  function inboxComposeTargetAllowsClaimable() {
+    return matchingComposeRecipientCount(this, inboxComposeTarget(this)) > 1;
+  }
+
+  function matchingComposeRecipientCount(vm, target) {
+    if (!target) return 0;
+    const candidates = vm.composeAgents.filter((agent) => !isBuiltInAgent(agent) && !isChannelAgent(agent));
+    if (target === "broadcast") return candidates.length;
+    if (vm.agentsById[target]) return 1;
+    if (target.startsWith("tag:")) {
+      const tag = target.slice(4);
+      return candidates.filter((agent) => (agent.tags || []).includes(tag)).length;
+    }
+    if (target.startsWith("cap:")) {
+      const cap = target.slice(4);
+      return candidates.filter((agent) => (agent.capabilities || []).includes(cap)).length;
+    }
+    if (target.startsWith("label:")) {
+      const label = target.slice(6);
+      return candidates.filter((agent) => agent.label === label).length;
+    }
+    return 1;
+  }
+
   function getUniqueLabels() {
     return [...new Set(visibleAgents(this).filter((agent) => agent.label).map((agent) => agent.label))];
   }
@@ -1089,13 +1164,22 @@
   }
 
   function visibleAgents(vm) {
-    return vm.showBuiltIns ? [...vm.agents] : vm.agents.filter((agent) => !isBuiltInAgent(agent));
+    const nonChannelAgents = vm.agents.filter((agent) => !isChannelAgent(agent));
+    return vm.showBuiltIns ? nonChannelAgents : nonChannelAgents.filter((agent) => !isBuiltInAgent(agent));
   }
 
   function isBuiltInAgent(agent) {
     return agent?.meta?.builtin === true || agent?.id === HUMAN_AGENT_ID || agent?.id === "system";
   }
 
+  function isChannelAgent(agent) {
+    return agent?.meta?.kind === "channel" || agent?.tags?.includes("channel");
+  }
+
+  function agentSupportsControlActions(agent) {
+    return Boolean(agent && !isBuiltInAgent(agent) && !isChannelAgent(agent));
+  }
+
   function applyAgentPreset(vm, list) {
     switch (vm.agentPresetFilter) {
       case "active":
@@ -1249,6 +1333,9 @@
       agentChannels,
       channelPresence,
       integrationPresence,
+      composeTargetAllowsClaimable,
+      inboxComposeTargetAllowsClaimable,
+      agentSupportsControlActions,
       timeAgo,
       fmtTime,
       healthAlertClass,
@@ -1368,6 +1455,7 @@
   function agentType(agent) {
     if (agent?.id === HUMAN_AGENT_ID) return "user";
     if (agent?.id === "system") return "system";
+    if (isChannelAgent(agent)) return "channel";
 
     const values = [
       ...(agent?.tags || []),
@@ -1573,6 +1661,12 @@
       openPairInvite,
       closePairInvite,
       doCreatePair,
+      openAgentSpawn,
+      closeAgentSpawn,
+      doSpawnAgent,
+      openAgentDirectoryBrowser,
+      browseAgentDirectory,
+      selectAgentDirectory,
       doSendPairMessage,
       doAcceptPair,
       doRejectPair,
@@ -1783,7 +1877,7 @@
   }
 
   function resetInboxComposeTarget() {
-    this.inboxCompose = { ...this.inboxCompose, to: "" };
+    this.inboxCompose = { ...this.inboxCompose, to: "", claimable: false };
   }
 
   function inboxComposeTarget(vm) {
@@ -1809,14 +1903,14 @@
       };
       if (this.inboxCompose.channel) payload.channel = this.inboxCompose.channel;
       if (this.inboxCompose.subject) payload.subject = this.inboxCompose.subject;
-      if (this.inboxCompose.claimable) payload.claimable = true;
+      if (this.inboxCompose.claimable && inboxComposeTargetAllowsClaimable.call(this)) payload.claimable = true;
       await this.api("POST", "/messages", payload);
       this.recordOperatorActivity({
-        title: this.inboxCompose.claimable ? "Claimable task sent" : "Message sent",
+        title: payload.claimable ? "Claimable task sent" : "Message sent",
         body: this.inboxCompose.subject || this.inboxCompose.body,
         meta: "to " + this.displayTarget(target),
-        icon: this.inboxCompose.claimable ? "ti-hand-grab" : "ti-send",
-        kind: this.inboxCompose.claimable ? "task" : "operator",
+        icon: payload.claimable ? "ti-hand-grab" : "ti-send",
+        kind: payload.claimable ? "task" : "operator",
         view: inboxPeer(payload) ? "inbox" : "messages",
         peer: inboxPeer(payload),
       });
@@ -1832,7 +1926,7 @@
     this.replyTo = { id: msg.id, from: msg.from };
     this.compose = {
       ...DEFAULT_COMPOSE,
-      from: this.view === "inbox" ? HUMAN_AGENT_ID : "",
+      from: HUMAN_AGENT_ID,
       to: replyTarget,
       channel: msg.channel || "",
     };
@@ -1852,7 +1946,7 @@
     if (vm.compose.channel) payload.channel = vm.compose.channel;
     if (vm.compose.subject) payload.subject = vm.compose.subject;
     if (vm.replyTo) payload.replyTo = vm.replyTo.id;
-    if (vm.compose.claimable) payload.claimable = true;
+    if (vm.compose.claimable && composeTargetAllowsClaimable.call(vm)) payload.claimable = true;
     return payload;
   }
 
@@ -1876,7 +1970,7 @@
       });
       this.composeOpen = false;
       this.replyTo = null;
-      this.compose = { ...DEFAULT_COMPOSE };
+      this.compose = { ...DEFAULT_COMPOSE, from: HUMAN_AGENT_ID };
       await this.fetchMessages();
     } catch (e) {
       alert("Send failed: " + e.message);
@@ -2313,6 +2407,77 @@
     }
   }
 
+  function openAgentSpawn() {
+    this.agentSpawn = { ...DEFAULT_AGENT_SPAWN };
+    this.agentDirectoryBrowser = { open: false, loading: false, path: "", parent: "", home: "", cwd: "", entries: [], error: "" };
+    this.agentSpawnOpen = true;
+    this.$nextTick(() => this.$refs?.agentSpawnCwd?.focus());
+  }
+
+  function closeAgentSpawn() {
+    this.agentSpawnOpen = false;
+    this.agentSpawn = { ...DEFAULT_AGENT_SPAWN };
+  }
+
+  async function openAgentDirectoryBrowser() {
+    this.agentDirectoryBrowser = { ...this.agentDirectoryBrowser, open: true };
+    await this.browseAgentDirectory(this.agentSpawn.cwd || "");
+  }
+
+  async function browseAgentDirectory(path) {
+    this.agentDirectoryBrowser = { ...this.agentDirectoryBrowser, loading: true, error: "" };
+    try {
+      const query = path ? "?path=" + encodeURIComponent(path) : "";
+      const listing = await this.api("GET", "/agents/spawn/directories" + query);
+      this.agentDirectoryBrowser = {
+        open: true,
+        loading: false,
+        path: listing.path || "",
+        parent: listing.parent || "",
+        home: listing.home || "",
+        cwd: listing.cwd || "",
+        entries: listing.entries || [],
+        error: "",
+      };
+      this.agentSpawn = { ...this.agentSpawn, cwd: listing.path || this.agentSpawn.cwd };
+    } catch (e) {
+      this.agentDirectoryBrowser = { ...this.agentDirectoryBrowser, loading: false, error: e.message };
+    }
+  }
+
+  function selectAgentDirectory(path) {
+    this.agentSpawn = { ...this.agentSpawn, cwd: path || this.agentDirectoryBrowser.path };
+    this.agentDirectoryBrowser = { ...this.agentDirectoryBrowser, open: false };
+  }
+
+  async function doSpawnAgent() {
+    if (this.agentSpawn.provider !== "codex") {
+      alert("Only Codex live sessions can be spawned from the dashboard right now.");
+      return;
+    }
+    try {
+      const payload = {
+        provider: "codex",
+        approvalMode: this.agentSpawn.approvalMode || "guarded",
+      };
+      if (this.agentSpawn.cwd) payload.cwd = this.agentSpawn.cwd;
+      if (this.agentSpawn.label) payload.label = this.agentSpawn.label;
+      const result = await this.api("POST", "/agents/spawn", payload);
+      this.recordOperatorActivity({
+        title: "Codex agent spawn requested",
+        body: result?.cwd || payload.cwd || "",
+        meta: result?.pid ? "pid " + result.pid : "starting",
+        icon: "ti-plus",
+        kind: "state",
+        view: "agents",
+      });
+      this.closeAgentSpawn();
+      await Promise.all([this.fetchAgents(), this.fetchActivityEvents()]);
+    } catch (e) {
+      alert("Spawn failed: " + e.message);
+    }
+  }
+
   function closePairMessage() {
     this.pairMessageOpen = false;
     this.pairMessage = { ...DEFAULT_PAIR_MESSAGE };
@@ -2409,6 +2574,16 @@
         this.agentDetailOpen = false;
       },
 
+      openChannelDetail(channel) {
+        if (!channel) return;
+        this.channelDetailId = channel.id;
+        this.channelDetailOpen = true;
+      },
+
+      closeChannelDetail() {
+        this.channelDetailOpen = false;
+      },
+
       openRename(agent) {
         this.renameModal = { show: true, agentId: agent.id, label: agent.label || "" };
         this.$nextTick(() => this.$refs.renameInput?.focus());
@@ -2438,6 +2613,26 @@
           alert("Delete failed: " + e.message);
         }
       },
+
+      async doAgentAction(agent, action) {
+        if (!agent || !action) return;
+        try {
+          const result = await this.api("POST", "/agents/" + encodeURIComponent(agent.id) + "/actions", { action });
+          this.recordOperatorActivity({
+            title: action === "restart" ? "Agent restart requested" : "Agent shutdown requested",
+            body: this.displayName(agent),
+            meta: agent.id,
+            icon: action === "restart" ? "ti-refresh" : "ti-power",
+            kind: "state",
+            view: "agents",
+            agentId: agent.id,
+            messageId: result?.message?.id,
+          });
+          await Promise.all([this.fetchMessages(), this.fetchActivityEvents()]);
+        } catch (e) {
+          alert("Agent action failed: " + e.message);
+        }
+      },
     };
   }
 
@@ -2495,7 +2690,7 @@
 
   function renderStatusChart() {
     const { labels, series } = countAgentStatuses(this.agents);
-    const colorMap = { online: "#48bb78", idle: "#48bb78", busy: "#ecc94b", offline: "#718096" };
+    const colorMap = { idle: "#4299e1", busy: "#ecc94b" };
 
     if (this.chartInstances.status) {
       this.chartInstances.status.updateOptions({
@@ -2522,10 +2717,12 @@
   }
 
   function countAgentStatuses(agents) {
-    const counts = { online: 0, idle: 0, busy: 0, offline: 0 };
-    for (const agent of agents) counts[agent.status] = (counts[agent.status] || 0) + 1;
+    const counts = { idle: 0, busy: 0 };
+    for (const agent of agents) {
+      if (agent.status in counts) counts[agent.status] += 1;
+    }
 
-    const labels = Object.keys(counts).filter((key) => counts[key] > 0);
+    const labels = Object.keys(counts);
     return { labels, series: labels.map((key) => counts[key]) };
   }
 

package/public/index.html

@@ -205,18 +205,21 @@
       </a>
       <a href="#" class="nav-link" :class="{ active: view === 'agents' }" @click.prevent="switchView('agents')">
         <i class="ti ti-robot"></i>Agents
-        <span class="badge bg-warning text-white ms-auto" x-show="attentionAgentCount > 0" x-text="attentionAgentCount"></span>
-        <span class="badge bg-success text-white ms-1" x-text="onlineCount"></span>
+        <span class="ms-auto d-inline-flex gap-1 align-items-center">
+          <span class="badge bg-warning text-white" x-show="attentionAgentCount > 0" x-text="attentionAgentCount"></span>
+          <span class="badge bg-success text-white" x-show="onlineCount > 0" x-text="onlineCount"></span>
+        </span>
       </a>
       <a href="#" class="nav-link" :class="{ active: view === 'channels' }" @click.prevent="switchView('channels')">
         <i class="ti ti-messages"></i>Channels
         <span class="badge bg-success text-white ms-auto" x-show="channelCards.filter((item) => item.ready).length > 0" x-text="channelCards.filter((item) => item.ready).length"></span>
-        <span class="badge bg-secondary text-white ms-1" x-text="channelCards.length"></span>
       </a>
       <a href="#" class="nav-link" :class="{ active: view === 'integrations' }" @click.prevent="switchView('integrations')">
         <i class="ti ti-plug-connected"></i>Integrations
-        <span class="badge bg-warning text-white ms-auto" x-show="integrationCards.some((item) => (item.taskStats?.waitingTasks || 0) > 0)" x-text="integrationCards.reduce((total, item) => total + (item.taskStats?.waitingTasks || 0), 0)"></span>
-        <span class="badge bg-secondary text-white ms-1" x-text="integrationCards.length"></span>
+        <span class="ms-auto d-inline-flex gap-1 align-items-center">
+          <span class="badge bg-warning text-white" x-show="integrationCards.some((item) => (item.taskStats?.waitingTasks || 0) > 0)" x-text="integrationCards.reduce((total, item) => total + (item.taskStats?.waitingTasks || 0), 0)"></span>
+          <span class="badge bg-secondary text-white" x-show="integrationCards.length > 0" x-text="integrationCards.length"></span>
+        </span>
       </a>
       <a href="#" class="nav-link" :class="{ active: view === 'inbox' }" @click.prevent="switchView('inbox')">
         <i class="ti ti-inbox"></i>Inbox
@@ -228,8 +231,10 @@
       </a>
       <a href="#" class="nav-link" :class="{ active: view === 'pairs' }" @click.prevent="switchView('pairs')">
         <i class="ti ti-link"></i>Pairs
-        <span class="badge bg-warning text-white ms-auto" x-show="attentionSummary.pendingPairInvites > 0" x-text="attentionSummary.pendingPairInvites"></span>
-        <span class="badge bg-primary text-white ms-1" x-text="pairs.length"></span>
+        <span class="ms-auto d-inline-flex gap-1 align-items-center">
+          <span class="badge bg-warning text-white" x-show="attentionSummary.pendingPairInvites > 0" x-text="attentionSummary.pendingPairInvites"></span>
+          <span class="badge bg-primary text-white" x-show="openPairCount > 0" x-text="openPairCount"></span>
+        </span>
       </a>
       <a href="#" class="nav-link" :class="{ active: view === 'messages' }" @click.prevent="switchView('messages')">
         <i class="ti ti-messages"></i>Messages
@@ -240,8 +245,10 @@
       </a>
       <a href="#" class="nav-link" :class="{ active: view === 'tasks' }" @click.prevent="switchView('tasks')">
         <i class="ti ti-checkup-list"></i>Tasks
-        <span class="badge bg-warning text-white ms-auto" x-show="attentionSummary.claimableTasks > 0" x-text="attentionSummary.claimableTasks"></span>
-        <span class="badge bg-secondary text-white ms-1" x-text="stats.openTasks ?? 0"></span>
+        <span class="ms-auto d-inline-flex gap-1 align-items-center">
+          <span class="badge bg-warning text-white" x-show="attentionSummary.claimableTasks > 0" x-text="attentionSummary.claimableTasks"></span>
+          <span class="badge bg-secondary text-white" x-show="(stats.openTasks ?? 0) > 0" x-text="stats.openTasks ?? 0"></span>
+        </span>
       </a>
       <a href="#" class="nav-link" :class="{ active: view === 'analytics' }" @click.prevent="switchView('analytics')">
         <i class="ti ti-chart-area-line"></i>Analytics
@@ -525,6 +532,9 @@
         <div class="d-flex align-items-center mb-3 gap-3 flex-wrap">
           <h2 class="page-title mb-0">Agents</h2>
           <div class="ms-auto d-flex gap-2 align-items-center">
+            <button class="btn btn-sm btn-primary" @click="openAgentSpawn()" title="Create Codex live agent">
+              <i class="ti ti-plus"></i>
+            </button>
             <select class="form-select form-select-sm" style="width:auto; min-width: 150px" x-model="agentPresetFilter">
               <option value="">View: All</option>
               <option value="active">View: Active agents</option>
@@ -663,10 +673,10 @@
         <div class="row g-3">
           <template x-for="channel in channelCards" :key="channel.id">
             <div class="col-md-6 col-xl-4">
-              <div class="card">
+              <div class="card" style="cursor:pointer" @click="if (!window.getSelection().toString()) openChannelDetail(channel)">
                 <div class="card-body">
                   <div class="d-flex align-items-start gap-2">
-                    <span class="agent-type-icon agent mt-0">
+                    <span class="agent-type-icon channel mt-0">
                       <i class="ti" :class="channelPresence(channel).icon"></i>
                     </span>
                     <div class="flex-grow-1 min-width-0">
@@ -696,8 +706,8 @@
                         <span x-text="'Last seen: ' + timeAgo(channel.lastSeen)"></span>
                       </div>
                     </div>
-                    <button class="btn btn-sm btn-ghost-secondary p-1" title="Show agent" @click="openAgentDetail(agentsById[channel.agentId])">
-                      <i class="ti ti-robot"></i>
+                    <button class="btn btn-sm btn-ghost-secondary p-1" title="Show channel" @click.stop="openChannelDetail(channel)">
+                      <i class="ti ti-messages"></i>
                     </button>
                   </div>
                 </div>
@@ -844,7 +854,7 @@
                 </select>
               </div>
               <div class="col-md-3">
-                <select class="form-select form-select-sm" x-model="inboxCompose.to">
+                <select class="form-select form-select-sm" x-model="inboxCompose.to" @change="if (!inboxComposeTargetAllowsClaimable()) inboxCompose.claimable = false">
                   <option value="">Target</option>
                   <template x-for="option in inboxComposeTargetOptions" :key="option.value">
                     <option :value="option.value" x-text="option.label"></option>
@@ -857,7 +867,7 @@
               <div class="col-md-2">
                 <input type="text" class="form-control form-control-sm" placeholder="Channel" x-model="inboxCompose.channel">
               </div>
-              <div class="col-md-2 d-flex gap-2 align-items-center">
+              <div class="col-md-2 d-flex gap-2 align-items-center" x-show="inboxComposeTargetAllowsClaimable()">
                 <label class="form-check mb-0">
                   <input type="checkbox" class="form-check-input" x-model="inboxCompose.claimable">
                   <span class="form-check-label small">Claimable</span>
@@ -1471,16 +1481,16 @@
           <div class="col-sm-6 col-lg-3">
             <div class="card">
               <div class="card-body text-center">
-                <div class="text-secondary small">Total Agents</div>
-                <div class="h2 mb-0" x-text="stats.agents ?? 0"></div>
+                <div class="text-secondary small">Agents</div>
+                <div class="h2 mb-0" x-text="onlineCount"></div>
               </div>
             </div>
           </div>
           <div class="col-sm-6 col-lg-3">
             <div class="card">
               <div class="card-body text-center">
-                <div class="text-secondary small">Online Now</div>
-                <div class="h2 mb-0 text-success" x-text="onlineCount"></div>
+                <div class="text-secondary small">Busy Agents</div>
+                <div class="h2 mb-0 text-warning" x-text="busyAgentCount"></div>
               </div>
             </div>
           </div>
@@ -1488,7 +1498,7 @@
             <div class="card">
               <div class="card-body text-center">
                 <div class="text-secondary small">Messages (24h)</div>
-	                <div class="h2 mb-0 text-info" x-text="stats.messagesLast24h ?? 0"></div>
+                <div class="h2 mb-0 text-info" x-text="stats.messagesLast24h ?? 0"></div>
               </div>
             </div>
           </div>
@@ -1612,6 +1622,16 @@
           <button class="btn btn-sm btn-ghost-secondary" @click="openRename(selectedAgentDetail)">
             <i class="ti ti-pencil me-1"></i>Rename
           </button>
+          <template x-if="agentSupportsControlActions(selectedAgentDetail)">
+            <button class="btn btn-sm btn-ghost-secondary" @click="openConfirm('Restart Agent', 'Restart agent ' + displayName(selectedAgentDetail) + '?', () => doAgentAction(selectedAgentDetail, 'restart'))">
+              <i class="ti ti-refresh me-1"></i>Restart
+            </button>
+          </template>
+          <template x-if="agentSupportsControlActions(selectedAgentDetail)">
+            <button class="btn btn-sm btn-ghost-danger" @click="openConfirm('Shutdown Agent', 'Shut down agent ' + displayName(selectedAgentDetail) + '?', () => doAgentAction(selectedAgentDetail, 'shutdown'))">
+              <i class="ti ti-power me-1"></i>Shutdown
+            </button>
+          </template>
         </div>
 
         <div class="p-3 border-bottom">
@@ -1766,6 +1786,141 @@
     </div>
   </template>
 
+  <!-- ==================== CHANNEL DETAIL DRAWER ==================== -->
+  <template x-if="selectedChannelDetail">
+    <div>
+      <div class="agent-drawer-backdrop" x-show="channelDetailOpen" x-cloak @click="closeChannelDetail()"></div>
+      <aside class="agent-drawer" x-show="channelDetailOpen" x-cloak>
+        <div class="p-3 border-bottom d-flex align-items-start gap-2">
+          <span class="agent-type-icon channel mt-1" title="Channel">
+            <i class="ti ti-messages"></i>
+          </span>
+          <div class="flex-grow-1 min-width-0">
+            <div class="d-flex align-items-center gap-2">
+              <span class="fw-bold text-truncate" x-text="selectedChannelDetail.name"></span>
+              <span class="badge" :class="'bg-' + channelPresence(selectedChannelDetail).tone + '-lt'">
+                <i class="ti me-1" :class="channelPresence(selectedChannelDetail).icon"></i><span x-text="channelPresence(selectedChannelDetail).label"></span>
+              </span>
+            </div>
+            <div class="text-secondary small text-truncate" x-text="selectedChannelDetail.id"></div>
+          </div>
+          <button class="btn btn-sm btn-ghost-secondary p-1" @click="closeChannelDetail()" title="Close">
+            <i class="ti ti-x"></i>
+          </button>
+        </div>
+
+        <div class="p-3 border-bottom d-flex gap-2 flex-wrap">
+          <button class="btn btn-sm btn-primary" @click="compose = { ...compose, from: 'user', to: selectedChannelDetail.target || selectedChannelDetail.agentId, channel: selectedChannelDetail.id, body: '', claimable: false }; composeOpen = true">
+            <i class="ti ti-send me-1"></i>Message
+          </button>
+          <button class="btn btn-sm btn-ghost-secondary" @click="channelFilter = selectedChannelDetail.id; switchView('messages'); closeChannelDetail()">
+            <i class="ti ti-filter me-1"></i>Messages
+          </button>
+          <template x-if="agentsById[selectedChannelDetail.agentId]">
+            <button class="btn btn-sm btn-ghost-secondary" @click="openAgentDetail(agentsById[selectedChannelDetail.agentId]); closeChannelDetail()">
+              <i class="ti ti-robot me-1"></i>Backing agent
+            </button>
+          </template>
+        </div>
+
+        <div class="p-3 border-bottom">
+          <h3 class="card-title mb-3">Route</h3>
+          <div class="detail-row mb-2">
+            <div class="text-secondary small">Target</div>
+            <div class="small text-break" x-text="displayTarget(selectedChannelDetail.target || selectedChannelDetail.agentId)"></div>
+          </div>
+          <div class="detail-row mb-2">
+            <div class="text-secondary small">Backing agent</div>
+            <div class="small text-break user-select-all" x-text="selectedChannelDetail.agentId"></div>
+          </div>
+          <div class="detail-row mb-2">
+            <div class="text-secondary small">Transport</div>
+            <div class="d-flex gap-1 flex-wrap">
+              <span class="badge bg-info-lt" x-text="selectedChannelDetail.type"></span>
+              <span class="badge bg-cyan-lt" x-text="selectedChannelDetail.transport || selectedChannelDetail.type"></span>
+              <span class="badge bg-secondary-lt" x-text="selectedChannelDetail.direction"></span>
+            </div>
+          </div>
+          <div class="detail-row mb-2">
+            <div class="text-secondary small">Last seen</div>
+            <div class="small" x-text="timeAgo(selectedChannelDetail.lastSeen)"></div>
+          </div>
+        </div>
+
+        <div class="p-3 border-bottom">
+          <h3 class="card-title mb-3">Capabilities</h3>
+          <div class="detail-row mb-2">
+            <div class="text-secondary small">Capabilities</div>
+            <div class="d-flex gap-1 flex-wrap">
+              <template x-for="capability in (selectedChannelDetail.capabilities || [])" :key="capability">
+                <span class="badge bg-purple-lt" x-text="capability"></span>
+              </template>
+              <template x-if="!(selectedChannelDetail.capabilities || []).length">
+                <span class="text-secondary small">-</span>
+              </template>
+            </div>
+          </div>
+          <div class="detail-row mb-2">
+            <div class="text-secondary small">Topics</div>
+            <div class="d-flex gap-1 flex-wrap">
+              <template x-for="topic in (selectedChannelDetail.topicChannels || [])" :key="topic">
+                <span class="badge bg-warning-lt" x-text="'#' + topic"></span>
+              </template>
+              <template x-if="!(selectedChannelDetail.topicChannels || []).length">
+                <span class="text-secondary small">-</span>
+              </template>
+            </div>
+          </div>
+          <div class="detail-row mb-2">
+            <div class="text-secondary small">Tags</div>
+            <div class="d-flex gap-1 flex-wrap">
+              <template x-for="tag in (selectedChannelDetail.tags || [])" :key="tag">
+                <span class="badge bg-cyan-lt" x-text="tag"></span>
+              </template>
+              <template x-if="!(selectedChannelDetail.tags || []).length">
+                <span class="text-secondary small">-</span>
+              </template>
+            </div>
+          </div>
+        </div>
+
+        <div class="p-3 border-bottom">
+          <h3 class="card-title mb-3">Metadata</h3>
+          <template x-for="entry in Object.entries(selectedChannelDetail.meta || {})" :key="entry[0]">
+            <div class="detail-row mb-2">
+              <div class="text-secondary small" x-text="entry[0]"></div>
+              <div class="small text-break" x-text="typeof entry[1] === 'object' ? JSON.stringify(entry[1]) : String(entry[1])"></div>
+            </div>
+          </template>
+          <template x-if="!Object.keys(selectedChannelDetail.meta || {}).length">
+            <div class="text-secondary small">No metadata</div>
+          </template>
+        </div>
+
+        <div class="p-3">
+          <h3 class="card-title mb-3">Recent Messages</h3>
+          <div class="list-group list-group-flush">
+            <template x-for="m in channelDetailMessages" :key="m.id">
+              <div class="list-group-item px-0">
+                <div class="d-flex align-items-center gap-2 mb-1">
+                  <span class="fw-bold small" x-text="displayTarget(m.from)"></span>
+                  <i class="ti ti-arrow-right text-secondary" style="font-size:12px"></i>
+                  <span class="small" x-text="displayTarget(m.to)"></span>
+                  <span class="badge bg-warning-lt" x-show="m.channel" x-text="'#' + m.channel"></span>
+                  <span class="text-secondary small ms-auto" x-text="'#' + m.id"></span>
+                </div>
+                <div class="text-secondary small text-truncate" x-text="messagePreview(m)"></div>
+              </div>
+            </template>
+            <template x-if="channelDetailMessages.length === 0">
+              <div class="text-secondary small">No recent channel messages loaded</div>
+            </template>
+          </div>
+        </div>
+      </aside>
+    </div>
+  </template>
+
   <!-- ==================== COMPOSE MODAL ==================== -->
   <div class="modal modal-blur" :class="{ show: composeOpen }" :style="composeOpen ? 'display:block' : 'display:none'" tabindex="-1" @click.self="composeOpen = false">
     <div class="modal-dialog modal-lg modal-dialog-centered">
@@ -1787,14 +1942,15 @@
               <label class="form-label">From</label>
               <select class="form-select" x-model="compose.from">
                 <option value="">Select sender…</option>
-                <template x-for="a in composeAgents" :key="a.id">
+                <option value="user">User [user]</option>
+                <template x-for="a in composeAgents.filter((agent) => agent.id !== 'user')" :key="a.id">
                   <option :value="a.id" x-text="displayName(a) + ' [' + a.id.slice(-6) + ']'"></option>
                 </template>
               </select>
             </div>
             <div class="col-md-6">
               <label class="form-label">To</label>
-              <select class="form-select" x-model="compose.to">
+              <select class="form-select" x-model="compose.to" @change="if (!composeTargetAllowsClaimable()) compose.claimable = false">
                 <option value="">Select recipient…</option>
                 <option value="broadcast">📢 Broadcast (all)</option>
                 <optgroup label="Labels">
@@ -1831,7 +1987,7 @@
               <label class="form-label">Message</label>
               <textarea class="form-control" rows="5" x-model="compose.body" placeholder="Type your message…" x-ref="composeBody"></textarea>
             </div>
-            <div class="col-12">
+            <div class="col-12" x-show="composeTargetAllowsClaimable()">
               <label class="form-check">
                 <input type="checkbox" class="form-check-input" x-model="compose.claimable">
                 <span class="form-check-label">Claimable task (only one agent can claim)</span>
@@ -1850,6 +2006,88 @@
   </div>
   <div class="modal-backdrop fade show" x-show="composeOpen" x-cloak></div>
 
+  <!-- ==================== AGENT SPAWN MODAL ==================== -->
+  <div class="modal modal-blur" :class="{ show: agentSpawnOpen }" :style="agentSpawnOpen ? 'display:block' : 'display:none'" tabindex="-1" @click.self="closeAgentSpawn()">
+    <div class="modal-dialog modal-md modal-dialog-centered">
+      <div class="modal-content">
+        <div class="modal-header">
+          <h5 class="modal-title">Create Agent</h5>
+          <button class="btn-close" @click="closeAgentSpawn()"></button>
+        </div>
+        <div class="modal-body">
+          <div class="row g-3">
+            <div class="col-12">
+              <label class="form-label">Provider</label>
+              <select class="form-select" x-model="agentSpawn.provider">
+                <option value="codex">Codex Live</option>
+              </select>
+            </div>
+            <div class="col-12">
+              <label class="form-label">Permission model</label>
+              <select class="form-select" x-model="agentSpawn.approvalMode">
+                <option value="guarded">Guarded</option>
+                <option value="read-only">Read-only</option>
+                <option value="open">Open</option>
+              </select>
+            </div>
+            <div class="col-12">
+              <label class="form-label">Working directory <span class="text-secondary">(optional)</span></label>
+              <div class="input-group">
+                <input type="text" class="form-control" x-model="agentSpawn.cwd" x-ref="agentSpawnCwd" placeholder="Defaults to the relay server working directory">
+                <button class="btn btn-ghost-secondary" @click="openAgentDirectoryBrowser()" title="Browse host directories">
+                  <i class="ti ti-folder-open me-1"></i>Browse
+                </button>
+              </div>
+              <div class="border rounded mt-2" x-show="agentDirectoryBrowser.open" x-cloak>
+                <div class="d-flex align-items-center gap-2 p-2 border-bottom">
+                  <button class="btn btn-sm btn-ghost-secondary" :disabled="!agentDirectoryBrowser.parent || agentDirectoryBrowser.loading" @click="browseAgentDirectory(agentDirectoryBrowser.parent)" title="Parent directory">
+                    <i class="ti ti-arrow-up"></i>
+                  </button>
+                  <button class="btn btn-sm btn-ghost-secondary" :disabled="!agentDirectoryBrowser.home || agentDirectoryBrowser.loading" @click="browseAgentDirectory(agentDirectoryBrowser.home)" title="Home directory">
+                    <i class="ti ti-home"></i>
+                  </button>
+                  <button class="btn btn-sm btn-ghost-secondary" :disabled="!agentDirectoryBrowser.cwd || agentDirectoryBrowser.loading" @click="browseAgentDirectory(agentDirectoryBrowser.cwd)" title="Server directory">
+                    <i class="ti ti-server"></i>
+                  </button>
+                  <div class="small text-secondary text-truncate flex-grow-1" x-text="agentDirectoryBrowser.path || 'Loading...'"></div>
+                  <button class="btn btn-sm btn-primary" :disabled="!agentDirectoryBrowser.path" @click="selectAgentDirectory(agentDirectoryBrowser.path)">Select</button>
+                </div>
+                <div class="p-2" style="max-height: 240px; overflow:auto">
+                  <template x-if="agentDirectoryBrowser.loading">
+                    <div class="text-secondary small py-3 text-center">Loading directories...</div>
+                  </template>
+                  <template x-if="agentDirectoryBrowser.error">
+                    <div class="alert alert-danger py-2 mb-2" x-text="agentDirectoryBrowser.error"></div>
+                  </template>
+                  <template x-for="entry in agentDirectoryBrowser.entries" :key="entry.path">
+                    <button type="button" class="list-group-item list-group-item-action d-flex align-items-center gap-2 w-100 text-start border-0 rounded" @click="browseAgentDirectory(entry.path)">
+                      <i class="ti ti-folder text-warning"></i>
+                      <span class="text-truncate" x-text="entry.name"></span>
+                    </button>
+                  </template>
+                  <template x-if="!agentDirectoryBrowser.loading && !agentDirectoryBrowser.error && agentDirectoryBrowser.entries.length === 0">
+                    <div class="text-secondary small py-3 text-center">No child directories</div>
+                  </template>
+                </div>
+              </div>
+            </div>
+            <div class="col-12">
+              <label class="form-label">Label <span class="text-secondary">(optional)</span></label>
+              <input type="text" class="form-control" x-model="agentSpawn.label" placeholder="e.g. backend helper">
+            </div>
+          </div>
+        </div>
+        <div class="modal-footer">
+          <button class="btn btn-ghost-secondary" @click="closeAgentSpawn()">Cancel</button>
+          <button class="btn btn-primary" @click="doSpawnAgent()">
+            <i class="ti ti-plus me-1"></i>Create
+          </button>
+        </div>
+      </div>
+    </div>
+  </div>
+  <div class="modal-backdrop fade show" x-show="agentSpawnOpen" x-cloak></div>
+
   <!-- ==================== PAIR INVITE MODAL ==================== -->
   <div class="modal modal-blur" :class="{ show: pairInviteOpen }" :style="pairInviteOpen ? 'display:block' : 'display:none'" tabindex="-1" @click.self="closePairInvite()">
     <div class="modal-dialog modal-lg modal-dialog-centered">

package/src/agent-spawn.ts

@@ -0,0 +1,137 @@
+import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, delimiter, dirname, join, resolve } from "node:path";
+
+export type CodexSpawnApprovalMode = "open" | "guarded" | "read-only";
+
+interface CodexSpawnInput {
+  cwd?: string;
+  approvalMode: CodexSpawnApprovalMode;
+  label?: string;
+  relayUrl: string;
+  token?: string;
+  dryRun?: boolean;
+}
+
+interface CodexSpawnResult {
+  provider: "codex";
+  pid?: number;
+  cwd: string;
+  approvalMode: CodexSpawnApprovalMode;
+  logPath: string;
+  command: string[];
+  dryRun?: boolean;
+}
+
+interface HostDirectoryEntry {
+  name: string;
+  path: string;
+}
+
+interface HostDirectoryListing {
+  path: string;
+  parent?: string;
+  home: string;
+  cwd: string;
+  entries: HostDirectoryEntry[];
+}
+
+export function normalizeCodexSpawnCwd(raw: string | undefined, fallback = process.cwd()): string {
+  const cwd = resolve(raw || fallback);
+  if (!existsSync(cwd) || !statSync(cwd).isDirectory()) {
+    throw new Error(`cwd does not exist or is not a directory: ${cwd}`);
+  }
+  return cwd;
+}
+
+export function listHostDirectories(raw: string | undefined): HostDirectoryListing {
+  const cwd = process.cwd();
+  const home = homedir();
+  const path = normalizeCodexSpawnCwd(raw || cwd, cwd);
+  const entries = readdirSync(path, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+    .map((entry) => ({
+      name: entry.name,
+      path: join(path, entry.name),
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const parent = dirname(path);
+  return {
+    path,
+    parent: parent !== path ? parent : undefined,
+    home,
+    cwd,
+    entries,
+  };
+}
+
+export function codexSpawnCommand(): string[] {
+  const override = process.env.AGENT_RELAY_CODEX_RELAY_BIN;
+  if (override) return [override];
+
+  const repoLauncher = resolve(import.meta.dir, "../codex/bin/agent-relay-codex.ts");
+  if (existsSync(repoLauncher)) return ["bun", "run", repoLauncher, "start"];
+
+  const fromPath = findOnPath("codex-relay");
+  if (fromPath) return [fromPath];
+
+  return ["codex-relay"];
+}
+
+export function codexSpawnLogPath(cwd: string, now = Date.now()): string {
+  const project = basename(cwd).replace(/[^a-zA-Z0-9._-]+/g, "-") || "project";
+  return join(homedir(), ".agent-relay", "spawns", `codex-${project}-${now}.log`);
+}
+
+export function spawnCodexAgent(input: CodexSpawnInput): CodexSpawnResult {
+  const cwd = normalizeCodexSpawnCwd(input.cwd);
+  const command = [
+    ...codexSpawnCommand(),
+    "--headless",
+    "--relay-url",
+    input.relayUrl,
+  ];
+  const logPath = codexSpawnLogPath(cwd);
+  const env: Record<string, string | undefined> = {
+    ...process.env,
+    AGENT_RELAY_CODEX_HEADLESS: "1",
+    AGENT_RELAY_APPROVAL: input.approvalMode,
+    AGENT_RELAY_TAGS: mergeCsv(process.env.AGENT_RELAY_TAGS, ["headless", "dashboard-spawned"]),
+    AGENT_RELAY_LABEL: input.label || process.env.AGENT_RELAY_LABEL,
+    AGENT_RELAY_URL: input.relayUrl,
+    AGENT_RELAY_TOKEN: input.token || process.env.AGENT_RELAY_TOKEN,
+  };
+
+  if (input.dryRun) {
+    return { provider: "codex", cwd, approvalMode: input.approvalMode, logPath, command, dryRun: true };
+  }
+
+  mkdirSync(dirname(logPath), { recursive: true });
+  const log = Bun.file(logPath);
+  const child = Bun.spawn(command, {
+    cwd,
+    env,
+    stdin: "ignore",
+    stdout: log,
+    stderr: log,
+  });
+  child.unref();
+
+  return { provider: "codex", pid: child.pid, cwd, approvalMode: input.approvalMode, logPath, command };
+}
+
+function mergeCsv(raw: string | undefined, additions: string[]): string {
+  return [...new Set([
+    ...(raw || "").split(",").map((item) => item.trim()).filter(Boolean),
+    ...additions,
+  ])].join(",");
+}
+
+function findOnPath(command: string): string | null {
+  for (const dir of (process.env.PATH || "").split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join(dir, command);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}

package/src/db.ts

@@ -1328,6 +1328,44 @@ function findMessageByIdempotencyKey(from: string, key: string): Message | null
   return row ? rowToMessage(row) : null;
 }
 
+function isDeliveryAgent(agent: AgentCard): boolean {
+  return agent.status !== "offline" &&
+    agent.id !== "user" &&
+    agent.id !== "system" &&
+    agent.meta?.kind !== "channel";
+}
+
+function matchingDeliveryAgents(target: string): AgentCard[] {
+  if (!target) return [];
+  const candidates = listAgents().filter(isDeliveryAgent);
+  if (target === "broadcast") return candidates;
+  const direct = getAgent(target);
+  if (direct) return isDeliveryAgent(direct) ? [direct] : [];
+  if (target.startsWith("tag:")) {
+    const tag = target.slice(4);
+    return candidates.filter((agent) => agent.tags.includes(tag));
+  }
+  if (target.startsWith("cap:")) {
+    const cap = target.slice(4);
+    return candidates.filter((agent) => agent.capabilities.includes(cap));
+  }
+  if (target.startsWith("label:")) {
+    const label = target.slice(6);
+    return candidates.filter((agent) => agent.label === label);
+  }
+  return [];
+}
+
+function claimableAllowedForTarget(target: string): boolean {
+  return matchingDeliveryAgents(target).length > 1;
+}
+
+function shouldStoreClaimable(input: SendMessageInput): boolean {
+  if (!input.claimable) return false;
+  if (input.type === "system" || typeof input.meta?.taskId === "number") return true;
+  return claimableAllowedForTarget(input.to);
+}
+
 export function sendMessageWithResult(input: SendMessageInput): { message: Message; created: boolean } {
   const now = Date.now();
 
@@ -1354,6 +1392,7 @@ export function sendMessageWithResult(input: SendMessageInput): { message: Messa
     VALUES ($from, $to, $type, $channel, $subject, $body, $threadId, $replyTo, $claimable, $idempotencyKey, $meta, $now)
   `);
   const setSelfThread = db.prepare("UPDATE messages SET thread_id = ? WHERE id = ?");
+  const claimable = shouldStoreClaimable(input);
 
   const id = db.transaction(() => {
     const result = insert.run({
@@ -1365,7 +1404,7 @@ export function sendMessageWithResult(input: SendMessageInput): { message: Messa
       $body: input.body,
       $threadId: threadId,
       $replyTo: input.replyTo ?? null,
-      $claimable: input.claimable ? 1 : 0,
+      $claimable: claimable ? 1 : 0,
       $idempotencyKey: input.idempotencyKey ?? null,
       $meta: JSON.stringify(input.meta ?? {}),
       $now: now,

package/src/routes.ts

@@ -52,6 +52,7 @@ import {
 } from "./db";
 import type { ActivityEventInput, ActivityKind, AgentCard, AgentSessionGuard, ChannelDirection, ChannelSummary, CreatePairInput, IntegrationEventInput, IntegrationSummary, PairActionInput, PairMessageInput, PairStatus, RegisterAgentInput, SendMessageInput, TaskStatus, TaskStatusInput } from "./types";
 import { getIntegrationTokens, INTEGRATION_RATE_LIMIT_PER_MINUTE, MAX_BODY_BYTES } from "./config";
+import { listHostDirectories, spawnCodexAgent, type CodexSpawnApprovalMode } from "./agent-spawn";
 import {
   getIntegrationAuth,
   hasIntegrationScope,
@@ -150,6 +151,9 @@ function parseQueryInt(
 }
 
 const VALID_AGENT_STATUSES = ["online", "idle", "busy", "offline"] as const;
+const VALID_AGENT_ACTIONS = ["restart", "shutdown"] as const;
+const VALID_AGENT_SPAWN_PROVIDERS = ["codex"] as const;
+const VALID_CODEX_SPAWN_APPROVALS = ["open", "guarded", "read-only"] as const;
 const VALID_TASK_SEVERITIES = ["info", "warning", "critical"] as const;
 const VALID_TASK_STATUSES = ["open", "claimed", "in_progress", "blocked", "done", "failed", "canceled"] as const;
 const VALID_PAIR_STATUSES = ["pending", "active", "ended", "rejected", "expired"] as const;
@@ -738,6 +742,119 @@ const deleteAgentById: Handler = (_req, params) => {
   return json({ ok: true });
 };
 
+function agentCanReceiveControlAction(agent: AgentCard): boolean {
+  return agent.id !== "user" &&
+    agent.id !== "system" &&
+    agent.meta?.kind !== "channel" &&
+    !agent.tags.includes("channel");
+}
+
+const postAgentAction: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("action required");
+    const action = cleanEnum(parsed.body.action, "action", VALID_AGENT_ACTIONS);
+    if (!action) return error("action required");
+    const agent = getAgent(params.id!);
+    if (!agent) return error("agent not found", 404);
+    if (!agentCanReceiveControlAction(agent)) return error("agent does not support dashboard control actions", 400);
+
+    const title = action === "restart" ? "Agent restart requested" : "Agent shutdown requested";
+    const msg = sendMessage({
+      from: "system",
+      to: agent.id,
+      type: "system",
+      subject: title,
+      body: action === "restart"
+        ? "Dashboard requested that this agent restart its relay-managed session now."
+        : "Dashboard requested that this agent shut down its relay-managed session now.",
+      meta: {
+        agentControl: {
+          action,
+          requestedBy: "dashboard",
+          requestedAt: Date.now(),
+        },
+        delivery: "interrupt",
+        priority: "urgent",
+      },
+    });
+    emitNewMessage(msg);
+    auditEvent({
+      clientId: "server-agent-" + agent.id + "-action-" + action + "-" + msg.id,
+      kind: "state",
+      title,
+      body: action,
+      meta: agent.id,
+      icon: action === "restart" ? "ti-refresh" : "ti-power",
+      view: "agents",
+      messageId: msg.id,
+      agentId: agent.id,
+      metadata: { action },
+    });
+    return json({ ok: true, action, message: msg }, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const postAgentSpawn: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("provider required");
+    const provider = cleanEnum(parsed.body.provider, "provider", VALID_AGENT_SPAWN_PROVIDERS);
+    if (provider !== "codex") return error("provider must be codex");
+    const approvalMode = cleanEnum(parsed.body.approvalMode, "approvalMode", VALID_CODEX_SPAWN_APPROVALS, "guarded") as CodexSpawnApprovalMode;
+    const cwd = cleanString(parsed.body.cwd, "cwd", { max: 500 });
+    const label = cleanString(parsed.body.label, "label", { max: 120 });
+    const relayUrl = process.env.AGENT_RELAY_SPAWN_RELAY_URL || process.env.AGENT_RELAY_URL || `http://127.0.0.1:${process.env.PORT || "4850"}`;
+    const token = req.headers.get("X-Agent-Relay-Token") ?? req.headers.get("Authorization")?.replace(/^Bearer\s+/i, "");
+    const result = spawnCodexAgent({
+      cwd,
+      approvalMode,
+      label,
+      relayUrl,
+      token: token || undefined,
+      dryRun: process.env.AGENT_RELAY_SPAWN_DRY_RUN === "1",
+    });
+    auditEvent({
+      clientId: "server-agent-spawn-codex-" + Date.now(),
+      kind: "state",
+      title: "Codex agent spawn requested",
+      body: result.cwd,
+      meta: result.pid ? `pid ${result.pid}` : "dry run",
+      icon: "ti-plus",
+      view: "agents",
+      metadata: {
+        provider: result.provider,
+        approvalMode: result.approvalMode,
+        pid: result.pid ?? null,
+        logPath: result.logPath,
+        dryRun: result.dryRun === true,
+      },
+    });
+    return json(result, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    if (e instanceof Error) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const getHostDirectories: Handler = (req) => {
+  try {
+    const url = new URL(req.url);
+    const path = cleanString(url.searchParams.get("path") ?? undefined, "path", { max: 500 });
+    return json(listHostDirectories(path));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    if (e instanceof Error) return error(e.message, 400);
+    throw e;
+  }
+};
+
 // --- Message routes ---
 
 const VALID_MSG_TYPES = ["message", "system"];
@@ -1412,14 +1529,17 @@ function route(method: string, path: string, handler: Handler): Route {
 
 const routes: Route[] = [
   route("POST", "/api/agents", postAgent),
+  route("POST", "/api/agents/spawn", postAgentSpawn),
   route("GET", "/api/agents", getAgents),
   route("GET", "/api/agents/find", findAgents),
+  route("GET", "/api/agents/spawn/directories", getHostDirectories),
   route("GET", "/api/agents/:id", getAgentById),
   route("PATCH", "/api/agents/:id/status", patchAgentStatus),
   route("PATCH", "/api/agents/:id/ready", patchAgentReady),
   route("PATCH", "/api/agents/:id/label", patchAgentLabel),
   route("PATCH", "/api/agents/:id/tags", patchAgentTags),
   route("POST", "/api/agents/:id/heartbeat", postHeartbeat),
+  route("POST", "/api/agents/:id/actions", postAgentAction),
   route("DELETE", "/api/agents/:id", deleteAgentById),
 
   route("POST", "/api/system/broadcast", postSystemBroadcast),