agent-relay-server 0.17.0 → 0.19.0

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.16.0",
+    "version": "0.17.0",
     "description": "Real-time message bus for inter-agent communication. Agent-first: this spec is designed for machine consumption — agents can self-discover the full API surface via GET /api/spec.",
     "license": {
       "name": "MIT",
@@ -3818,6 +3818,58 @@
         ]
       }
     },
+    "/api/workspaces/actions/cleanup-stale": {
+      "post": {
+        "operationId": "postWorkspaceCleanupStale",
+        "summary": "Post Workspace Cleanup Stale",
+        "tags": [
+          "Other"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "repoRoot": {
+                    "type": "string"
+                  },
+                  "dryRun": {
+                    "type": "string"
+                  },
+                  "landedOnly": {
+                    "type": "string"
+                  },
+                  "offlineOwnerOnly": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
     "/api/workspaces/{id}": {
       "get": {
         "operationId": "getWorkspaceById",
@@ -4005,6 +4057,54 @@
         ]
       }
     },
+    "/api/workspaces/{id}/diagnostics": {
+      "get": {
+        "operationId": "getWorkspaceDiagnostics",
+        "summary": "Get Workspace Diagnostics",
+        "tags": [
+          "Other"
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
     "/api/workspaces/{id}/diff": {
       "get": {
         "operationId": "getWorkspaceDiff",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -33,7 +33,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-sdk": "0.2.8"
+    "agent-relay-sdk": "0.2.10"
   },
   "scripts": {
     "prepack": "bun run build:dashboard:bundle >&2",

package/public/index.html

@@ -10816,6 +10816,25 @@ var PAIR_STATUS_COLORS = {
 	expired: "bg-red-500/20 text-red-400"
 };
 //#endregion
+//#region ../sdk/src/types.ts
+/** True for a non-null, non-array object. The canonical type guard for the whole repo. */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Narrow `unknown` to a non-empty trimmed string, else `undefined`.
+* Settled semantics: whitespace-only is treated as empty (returns `undefined`).
+*/
+function stringValue(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : void 0;
+}
+/** Extract a human-readable message from any thrown value. */
+function errMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
 //#region src/lib/display.ts
 function toTimestamp(value) {
 	const ts = typeof value === "number" ? value : new Date(value || 0).getTime();
@@ -10901,7 +10920,7 @@ function isAgentStale(now, agent) {
 	if (!agent?.lastSeen || agent.status === "offline") return false;
 	if (agent.id === "user" || agent.id === "system") return false;
 	const transport = agent.meta?.transport;
-	if (isRecord$2(transport) && transport.connected === true) return false;
+	if (isRecord(transport) && transport.connected === true) return false;
 	const lastSeenMs = new Date(agent.lastSeen).getTime();
 	if (!Number.isFinite(lastSeenMs)) return false;
 	return now - lastSeenMs > 6e4;
@@ -11060,7 +11079,7 @@ function messageMatchesChannel(message, channel) {
 }
 function providerRuntimeState(agent) {
 	const raw = agent?.meta?.providerState;
-	if (!isRecord$2(raw) || typeof raw.state !== "string") return null;
+	if (!isRecord(raw) || typeof raw.state !== "string") return null;
 	return {
 		state: raw.state,
 		reason: typeof raw.reason === "string" ? raw.reason : void 0,
@@ -11073,16 +11092,16 @@ function providerRuntimeState(agent) {
 	};
 }
 function providerPendingApproval(value) {
-	if (!isRecord$2(value) || typeof value.id !== "string") return void 0;
-	const choices = Array.isArray(value.choices) ? value.choices.filter(isRecord$2).map((choice) => ({
+	if (!isRecord(value) || typeof value.id !== "string") return void 0;
+	const choices = Array.isArray(value.choices) ? value.choices.filter(isRecord).map((choice) => ({
 		id: choice.id,
 		label: typeof choice.label === "string" ? choice.label : String(choice.id || "")
 	})).filter((choice) => (choice.id === "approve" || choice.id === "approve-session" || choice.id === "deny" || choice.id === "abort") && Boolean(choice.label)) : [];
-	const questions = Array.isArray(value.questions) ? value.questions.filter(isRecord$2).map((q) => ({
+	const questions = Array.isArray(value.questions) ? value.questions.filter(isRecord).map((q) => ({
 		question: typeof q.question === "string" ? q.question : "",
 		header: typeof q.header === "string" ? q.header : void 0,
 		multiSelect: q.multiSelect === true,
-		options: Array.isArray(q.options) ? q.options.filter(isRecord$2).map((o) => ({
+		options: Array.isArray(q.options) ? q.options.filter(isRecord).map((o) => ({
 			label: typeof o.label === "string" ? o.label : String(o.label ?? ""),
 			description: typeof o.description === "string" ? o.description : void 0
 		})).filter((o) => Boolean(o.label)) : []
@@ -11110,7 +11129,7 @@ function activeSubagents(agent) {
 			label: `Subagent ${index + 1}`
 		})) : [];
 	}
-	return raw.filter(isRecord$2).map((item, index) => {
+	return raw.filter(isRecord).map((item, index) => {
 		const id = typeof item.id === "string" && item.id ? item.id : `subagent-${index + 1}`;
 		const role = typeof item.role === "string" && item.role ? item.role : void 0;
 		return {
@@ -11256,9 +11275,6 @@ function presenceBadges(agent, attention, pair) {
 	});
 	return badges;
 }
-function isRecord$2(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function emptyAttention() {
 	return {
 		unread: 0,
@@ -11525,7 +11541,7 @@ function downloadText(filename, text, type) {
 	URL.revokeObjectURL(url);
 }
 //#endregion
-//#region ../sdk/dist/provider-catalog.js
+//#region ../sdk/src/provider-catalog.ts
 var CLAUDE_LOW_TO_MAX = [
 	"low",
 	"medium",
@@ -108614,9 +108630,6 @@ function workspaceMode(agent) {
 function recordValue(value) {
 	return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
-function stringValue(value) {
-	return typeof value === "string" && value.trim() ? value.trim() : void 0;
-}
 function runtimeBadges(agent) {
 	const caps = agent.providerCapabilities;
 	const context = agent.context;
@@ -123768,7 +123781,7 @@ function TerminalViewer({ orchestratorId, session, interactive: initialInteracti
 		try {
 			writeSnapshot(await apiCall("GET", `/orchestrators/${encodeURIComponent(orchestratorId)}/terminal/${encodeURIComponent(session)}`));
 		} catch (e) {
-			setError(e instanceof Error ? e.message : String(e));
+			setError(errMessage(e));
 		} finally {
 			inFlightRef.current = false;
 		}
@@ -123825,7 +123838,7 @@ function TerminalViewer({ orchestratorId, session, interactive: initialInteracti
 		for (const chunk of chunks) inputQueueRef.current = inputQueueRef.current.then(() => apiCall("POST", `/orchestrators/${encodeURIComponent(orchestratorId)}/terminal/${encodeURIComponent(session)}/input`, { data: chunk })).then(() => {
 			setError(null);
 		}).catch((e) => {
-			setError(e instanceof Error ? e.message : String(e));
+			setError(errMessage(e));
 		});
 	}
 	function handleTerminalData(data) {
@@ -124420,7 +124433,7 @@ function useFileRead(orchestratorId, selectedPath) {
 		}).catch((e) => {
 			if (!cancelled) {
 				setFile(null);
-				setError(e instanceof Error ? e.message : String(e));
+				setError(errMessage(e));
 			}
 		}).finally(() => {
 			if (!cancelled) setLoading(false);
@@ -124458,7 +124471,7 @@ function useFileListing(orchestratorId, selectedPath, git = false) {
 		}).catch((e) => {
 			if (!cancelled) {
 				setListing(null);
-				setError(e instanceof Error ? e.message : String(e));
+				setError(errMessage(e));
 			}
 		}).finally(() => {
 			if (!cancelled) setLoading(false);
@@ -124774,7 +124787,7 @@ function FileBrowser({ overlay = false }) {
 			setPathDraft(result.path);
 			setReadError("");
 		} catch (e) {
-			setError(e instanceof Error ? e.message : String(e));
+			setError(errMessage(e));
 		} finally {
 			setLoading(false);
 		}
@@ -128115,7 +128128,7 @@ function LogViewer({ orchestratorId, session, lines = 200 }) {
 			setLogLines((await apiCall("GET", `/orchestrators/${encodeURIComponent(orchestratorId)}/logs/${encodeURIComponent(session)}?lines=${lines}${stream === "mirror" ? "&stream=mirror" : ""}`)).lines || []);
 			setError(null);
 		} catch (e) {
-			setError(e instanceof Error ? e.message : String(e));
+			setError(errMessage(e));
 		}
 	}
 	(0, import_react.useEffect)(() => {
@@ -152917,7 +152930,7 @@ function InsightsView() {
 			setProjects(obs.projects);
 			setNow(Date.now());
 		} catch (e) {
-			setError(e instanceof Error ? e.message : String(e));
+			setError(errMessage(e));
 		}
 	}
 	(0, import_react.useEffect)(() => {
@@ -152937,7 +152950,7 @@ function InsightsView() {
 			setVersion(entry.version);
 		} catch (e) {
 			setConfig(previous);
-			setError(e instanceof Error ? e.message : String(e));
+			setError(errMessage(e));
 		} finally {
 			setSaving(false);
 		}
@@ -154067,7 +154080,7 @@ function AgentDiagnostics({ agent, orchestrators }) {
 	});
 	const policyName = typeof agent.meta?.policyName === "string" ? agent.meta.policyName : null;
 	const profileName = typeof agent.meta?.profile === "string" ? agent.meta.profile : null;
-	const agentProfile = isRecord$1(agent.meta?.agentProfile) ? agent.meta.agentProfile : null;
+	const agentProfile = isRecord(agent.meta?.agentProfile) ? agent.meta.agentProfile : null;
 	const profileProjection = isProfileProjectionReport(agentProfile?.projection) ? agentProfile.projection : null;
 	const managedOrch = orchestrators.find((o) => o.managedAgents.some((m) => m.agentId === agent.id));
 	const managedAgent = managedOrch?.managedAgents.find((m) => m.agentId === agent.id);
@@ -154558,11 +154571,8 @@ function CollapsibleSection({ title, expanded, onToggle, children }) {
 		})]
 	});
 }
-function isRecord$1(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function isProfileProjectionReport(value) {
-	return isRecord$1(value) && typeof value.profileName === "string" && typeof value.provider === "string" && typeof value.base === "string" && Array.isArray(value.entries) && Array.isArray(value.warnings) && Array.isArray(value.unsupported);
+	return isRecord(value) && typeof value.profileName === "string" && typeof value.provider === "string" && typeof value.base === "string" && Array.isArray(value.entries) && Array.isArray(value.warnings) && Array.isArray(value.unsupported);
 }
 function KV({ label, value, className = "", mono = false }) {
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
@@ -155753,9 +155763,6 @@ function orchestratorForAgentTerminal(agent, session, orchestrators) {
 	if (!agent) return null;
 	return orchestrators.find((orchestrator) => orchestrator.managedAgents.some((managed) => managed.agentId === agent.id || managed.tmuxSession === session)) ?? null;
 }
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 //#endregion
 //#region src/components/drawers/channel-detail-drawer.tsx
 function ChannelDetailDrawer() {
@@ -156467,7 +156474,7 @@ function DirectoryBrowserDialog({ open, onOpenChange, onSelect, orchestratorId,
 			const query = path ? `?path=${encodeURIComponent(path)}` : "";
 			setListing(await apiCall("GET", `/orchestrators/${encodeURIComponent(orchestratorId)}/directories${query}`));
 		} catch (e) {
-			setError(e instanceof Error ? e.message : String(e));
+			setError(errMessage(e));
 		} finally {
 			setLoading(false);
 		}
@@ -156491,7 +156498,7 @@ function DirectoryBrowserDialog({ open, onOpenChange, onSelect, orchestratorId,
 			setCreating(false);
 			setNewDirName("");
 		} catch (e) {
-			setCreateError(e instanceof Error ? e.message : String(e));
+			setCreateError(errMessage(e));
 		}
 	}
 	function handleSelect() {

package/public/sw.js

@@ -1,4 +1,4 @@
-const CACHE_NAME = "agent-relay-dashboard-v1";
+const CACHE_NAME = "agent-relay-dashboard-v2";
 const scopeUrl = new URL(self.registration.scope);
 const scopePath = scopeUrl.pathname.endsWith("/") ? scopeUrl.pathname : `${scopeUrl.pathname}/`;
 const appUrl = (path) => new URL(path, self.registration.scope).toString();
@@ -11,10 +11,30 @@ const APP_SHELL = [
   appUrl("icons/agent-relay-512.png"),
 ];
 
+// The server may send the shell brotli/gzip-encoded. fetch() exposes the body
+// already decoded but leaves Content-Encoding / Content-Length headers on the
+// response — caching that verbatim risks a double-decode or
+// ERR_CONTENT_LENGTH_MISMATCH on replay. Re-wrap with those headers stripped so
+// the cached copy is clean identity bytes.
+async function cacheNormalized(cache, key, response) {
+  const body = await response.clone().arrayBuffer();
+  const headers = new Headers(response.headers);
+  headers.delete("Content-Encoding");
+  headers.delete("Content-Length");
+  await cache.put(key, new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  }));
+}
+
 self.addEventListener("install", (event) => {
   event.waitUntil(
     caches.open(CACHE_NAME)
-      .then((cache) => cache.addAll(APP_SHELL))
+      .then((cache) => Promise.all(APP_SHELL.map(async (href) => {
+        const response = await fetch(href, { cache: "reload" });
+        if (response.ok) await cacheNormalized(cache, href, response);
+      })))
       .then(() => self.skipWaiting()),
   );
 });
@@ -45,20 +65,35 @@ self.addEventListener("fetch", (event) => {
     return;
   }
 
+  // Stale-while-revalidate for the app shell and SPA navigations: serve the
+  // cached bundle instantly (the ~10 MB unminified shell never blocks the
+  // network on a slow/high-latency link) and refresh it in the background.
+  // SPA route navigations all resolve to index.html, so key them there to avoid
+  // fragmenting the cache by query string / deep-link path.
+  const isNavigation = request.mode === "navigate";
+  if (isNavigation || APP_SHELL.includes(url.href)) {
+    event.respondWith(staleWhileRevalidate(request, isNavigation ? appUrl("index.html") : request));
+    return;
+  }
+
+  // Other same-scope assets: network-first, fall back to cache when offline.
   event.respondWith(
-    fetch(request)
-      .then((response) => {
-        if (response.ok && APP_SHELL.includes(url.href)) {
-          const copy = response.clone();
-          caches.open(CACHE_NAME).then((cache) => cache.put(request, copy));
-        }
-        return response;
-      })
-      .catch(async () => {
-        const cached = await caches.match(request);
-        if (cached) return cached;
-        if (request.mode === "navigate") return caches.match(appUrl("index.html"));
-        throw new Error("offline");
-      }),
+    fetch(request).catch(() => caches.match(request).then((c) => {
+      if (c) return c;
+      throw new Error("offline");
+    })),
   );
 });
+
+async function staleWhileRevalidate(request, cacheKey) {
+  const cache = await caches.open(CACHE_NAME);
+  const cached = await cache.match(cacheKey);
+  const network = fetch(request)
+    .then(async (response) => {
+      if (response.ok) await cacheNormalized(cache, cacheKey, response);
+      return response;
+    })
+    .catch(() => cached);
+  // Return cache immediately when present; otherwise wait for the network.
+  return cached || network;
+}

package/runner/src/adapter.ts

@@ -1,4 +1,5 @@
 import type { AgentProfile, Message } from "agent-relay-sdk";
+import { isRecord } from "agent-relay-sdk";
 
 export type SemanticStatus = "idle" | "busy" | "offline" | "error";
 type ProviderWorkKind = "provider-turn" | "subagent";
@@ -160,10 +161,6 @@ export const RELAY_CONTEXT = `[agent-relay] You are connected to Agent Relay, a
 
 const PROVIDER_MESSAGE_BODY_PREVIEW_CHARS = 4000;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-
 function attachmentRefs(message: Message): Record<string, unknown>[] {
   const payloadRefs = message.payload?.attachments;
   const topLevelRefs = (message as Message & { attachments?: unknown }).attachments;

package/runner/src/config.ts

@@ -1,6 +1,8 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { join, resolve } from "node:path";
+import { stringValue } from "agent-relay-sdk";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import type { ProviderConfig } from "./adapter";
 
 interface GlobalRunnerConfig {
@@ -97,7 +99,7 @@ export function providerConfigPublic(config: LoadedProviderConfig): Record<strin
 
 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();
+  const cleanLabel = sanitizeFsName(label || project, { replacement: "-", lowercase: true });
   return `${hostname()}-${provider}-${cleanLabel}-${crypto.randomUUID().slice(0, 8)}`;
 }
 
@@ -115,10 +117,6 @@ function readJson(path: string): Record<string, unknown> {
   }
 }
 
-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;
 }

package/scripts/orchestrator-spawn-smoke.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { hostname } from "node:os";
+import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 
 type Orchestrator = {
   id: string;
@@ -44,7 +45,7 @@ relayUrl = relayUrl.replace(/\/+$/, "");
 
 function headers(): Record<string, string> {
   const h: Record<string, string> = { "Content-Type": "application/json" };
-  if (process.env.AGENT_RELAY_TOKEN) h["X-Agent-Relay-Token"] = process.env.AGENT_RELAY_TOKEN;
+  if (process.env.AGENT_RELAY_TOKEN) h[RELAY_TOKEN_HEADER] = process.env.AGENT_RELAY_TOKEN;
   return h;
 }