agent-relay-server 0.17.0 → 0.18.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.18.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.9"
   },
   "scripts": {
     "prepack": "bun run build:dashboard:bundle >&2",

package/public/index.html

@@ -10816,6 +10816,21 @@ 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;
+}
+//#endregion
 //#region src/lib/display.ts
 function toTimestamp(value) {
 	const ts = typeof value === "number" ? value : new Date(value || 0).getTime();
@@ -10901,7 +10916,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 +11075,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 +11088,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 +11125,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 +11271,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 +11537,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 +108626,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;
@@ -154067,7 +154076,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 +154567,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 +155759,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() {

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,7 @@
 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 type { ProviderConfig } from "./adapter";
 
 interface GlobalRunnerConfig {
@@ -115,10 +116,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;
 }
 

package/src/automations.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { parseJson } from "./utils";
 import {
   getAgent,
   getDb,
@@ -12,8 +13,11 @@ import {
   ValidationError,
 } from "./db";
 import { createCommand } from "./commands-db";
-import { getAgentProfile, getSpawnPolicy, workspaceSpawnParams } from "./config-store";
-import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { cleanString } from "./validation";
+import { getAgentProfile, getSpawnPolicy } from "./config-store";
+import { buildSpawnCommand, resolveSpawnModelParams } from "./spawn-command";
+import { resolveProviderSelection, type ProviderEffort, VALID_EFFORTS } from "agent-relay-sdk/provider-catalog";
+import { VALID_WORKSPACE_MODES } from "agent-relay-sdk";
 import { runnerRuntimeTokenEnv } from "./runtime-tokens";
 import type {
   AgentCard,
@@ -43,8 +47,6 @@ const BLOCKING_RUN_STATUSES = new Set<AutomationRunStatus>(["dispatching", "wait
 const OPEN_RUN_STATUSES = new Set<AutomationRunStatus>(["scheduled", "dispatching", "waiting_agent", "running"]);
 const CLOSED_TASK_STATUS = new Set(["done", "failed", "canceled"]);
 const MAX_CRON_SCAN_MINUTES = 366 * 24 * 60;
-const VALID_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
-const VALID_WORKSPACE_MODES = ["isolated", "shared", "inherit"] as const;
 const MIN_RUNTIME_BUDGET_MS = 60_000;
 const MAX_RUNTIME_BUDGET_MS = 24 * 60 * 60 * 1000;
 
@@ -75,15 +77,6 @@ function ensureAutomationTables(): void {
   initializedDb = current;
 }
 
-function parseJson<T>(value: unknown, fallback: T): T {
-  if (typeof value !== "string" || !value) return fallback;
-  try {
-    return JSON.parse(value) as T;
-  } catch {
-    return fallback;
-  }
-}
-
 function rowToAutomation(row: any): Automation {
   return {
     id: row.id,
@@ -126,18 +119,6 @@ function rowToAutomationRun(row: any): AutomationRun {
   };
 }
 
-function cleanString(value: unknown, field: string, opts: { required?: boolean; max?: number } = {}): string | undefined {
-  if (value === undefined || value === null) {
-    if (opts.required) throw new ValidationError(`${field} required`);
-    return undefined;
-  }
-  if (typeof value !== "string") throw new ValidationError(`${field} must be a string`);
-  const trimmed = value.trim();
-  if (opts.required && !trimmed) throw new ValidationError(`${field} required`);
-  if (opts.max && trimmed.length > opts.max) throw new ValidationError(`${field} must be ${opts.max} characters or fewer`);
-  return trimmed || undefined;
-}
-
 function cleanStringArray(value: unknown, field: string): string[] | undefined {
   if (value === undefined || value === null) return undefined;
   if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array`);
@@ -544,22 +525,17 @@ function dispatchOnDemandAutomation(
   now: number,
 ): AutomationDispatchResult {
   if (!orchestrator.providers.includes(policy.provider)) throw new ValidationError(`orchestrator ${orchestrator.id} does not have provider available: ${policy.provider}`);
-  const selection = resolveProviderSelection({ provider: policy.provider, model: policy.model, effort: policy.effort });
   const agentProfile = policy.profile ? getAgentProfile(policy.profile)?.value : undefined;
   const label = automationRunLabel(automation.id, run.id);
   const command = createCommand({
     type: "agent.spawn",
     source: "automation",
     target: orchestrator.agentId,
-    params: {
-      action: "spawn",
+    params: buildSpawnCommand({
       provider: policy.provider,
-      model: selection.modelAlias,
-      providerModel: selection.providerModel,
-      effort: selection.effort,
+      modelParams: resolveSpawnModelParams(policy.provider, policy.model, policy.effort),
       profile: policy.profile,
       agentProfile,
-      ...workspaceSpawnParams(),
       cwd: policy.cwd || orchestrator.baseDir,
       workspaceMode: policy.workspaceMode ?? "inherit",
       label,
@@ -575,7 +551,7 @@ function dispatchOnDemandAutomation(
         label,
         createdBy: "automation",
       }),
-    },
+    }),
   });
   const result = createRunTask(automation, run, `label:${label}`, now, {
     targetMode: "on_demand_agent",

package/src/bus.ts

@@ -3,6 +3,7 @@ import { createActivityEvent, getAgent, getDb, heartbeat, markReady, mergeAgentM
 import { getOldestOutboxCursor, getOutboxCursor, replayEvents, type BusEvent } from "./bus-outbox";
 import { emitRelayEvent, subscribeRelayEvents, type RelayEvent } from "./events";
 import { createCommand, getCommand, updateCommand } from "./commands-db";
+import { emitCommandEvent } from "./command-events";
 import { getLifecycleManager } from "./lifecycle-manager";
 import { noteAgentTimelineEvent, noteCompactionCommandCompleted } from "./compaction-watch";
 import { applyCommandToRecipe } from "./recipe-runner";
@@ -13,6 +14,7 @@ import {
   type BusFrame,
   type RegisterFrame,
 } from "agent-relay-sdk/protocol";
+import { isRecord, stringValue } from "agent-relay-sdk";
 import { getComponentAuth, isComponentAuthorizedFor, isAuthorized, isOriginAllowed, unauthorized } from "./security";
 import type { AgentCard, Command, ComponentToken, ContextState, Message, ProviderCapabilities, Task } from "./types";
 
@@ -611,15 +613,6 @@ function providerStateKey(state: Record<string, unknown> | null): string | null
   return [state.state, typeof state.reason === "string" ? state.reason : ""].join(":");
 }
 
-function emitCommandEvent(command: Command, type: string): void {
-  emitRelayEvent({
-    type,
-    source: command.source,
-    subject: command.id,
-    data: { command },
-  });
-}
-
 function sendCommandResult(
   ws: BusWebSocket,
   commandId: string,
@@ -638,14 +631,6 @@ function sendCommandResult(
   });
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-
 function send(ws: BusWebSocket, frame: Record<string, unknown>): void {
   ws.send(JSON.stringify(frame));
 }