agent-relay-server 0.87.0 → 0.88.1

package/src/ntfy.ts

@@ -0,0 +1,222 @@
+import { Buffer } from "node:buffer";
+import { MAX_BODY_BYTES } from "./config";
+import { getConfig } from "./config-store";
+import { upsertAgent, ValidationError } from "./db";
+import { registerChannelTypeSetting } from "./settings/modules";
+import { cleanString, cleanStringArray } from "./validation";
+import { errMessage, isRecord, type JSONSchema } from "agent-relay-sdk";
+
+export const NTFY_CONFIG_NAMESPACE = "channel-type";
+export const NTFY_CONFIG_KEY = "ntfy";
+export const NTFY_CHANNEL_ID = "ntfy:default";
+
+export const NTFY_PRIORITIES = ["min", "low", "default", "high", "urgent"] as const;
+export type NtfyPriority = (typeof NTFY_PRIORITIES)[number];
+
+export interface NtfyChannelConfig {
+  enabled: boolean;
+  serverUrl: string;
+  topic: string;
+  tokenEnv?: string;
+  username?: string;
+  passwordEnv?: string;
+  defaultTags: string[];
+  defaultClick?: string;
+  timeoutMs: number;
+}
+
+export interface NtfyNotificationInput {
+  title: string;
+  body: string;
+  priority?: NtfyPriority;
+  tags?: string[];
+  click?: string;
+}
+
+export interface NtfyNotificationResult {
+  ok: true;
+  status: number;
+  channelId: string;
+  topic: string;
+  priority: NtfyPriority;
+  tags: string[];
+}
+
+const DEFAULT_NTFY_CONFIG: NtfyChannelConfig = {
+  enabled: false,
+  serverUrl: "",
+  topic: "",
+  defaultTags: [],
+  timeoutMs: 15_000,
+};
+
+const NTFY_CONFIG_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["enabled", "serverUrl", "topic"],
+  properties: {
+    enabled: { type: "boolean" },
+    serverUrl: { type: "string", maxLength: 500 },
+    topic: { type: "string", maxLength: 200 },
+    tokenEnv: { type: "string", maxLength: 120, pattern: "^[A-Z0-9_]+$" },
+    username: { type: "string", maxLength: 120 },
+    passwordEnv: { type: "string", maxLength: 120, pattern: "^[A-Z0-9_]+$" },
+    defaultTags: { type: "array", maxItems: 20, items: { type: "string", maxLength: 40 } },
+    defaultClick: { type: "string", maxLength: 1000 },
+    timeoutMs: { type: "integer", minimum: 1_000, maximum: 60_000 },
+  },
+};
+
+registerChannelTypeSetting({
+  type: NTFY_CONFIG_KEY,
+  schema: NTFY_CONFIG_SCHEMA,
+  defaults: DEFAULT_NTFY_CONFIG,
+  display: {
+    label: "ntfy outgoing channel",
+    description: "Configures the built-in egress-only ntfy notification channel.",
+    order: 121,
+  },
+});
+
+export function getNtfyConfig(): NtfyChannelConfig {
+  const stored = getConfig<Partial<NtfyChannelConfig>>(NTFY_CONFIG_NAMESPACE, NTFY_CONFIG_KEY)?.value;
+  return normalizeNtfyConfig({ ...DEFAULT_NTFY_CONFIG, ...(isRecord(stored) ? stored : {}) });
+}
+
+export async function sendNtfyNotification(input: NtfyNotificationInput): Promise<NtfyNotificationResult> {
+  const config = getNtfyConfig();
+  validateSendConfig(config);
+  const title = cleanString(input.title, "title", { required: true, max: 200 })!;
+  const body = cleanString(input.body, "body", { required: true, max: MAX_BODY_BYTES })!;
+  const priority = input.priority ?? "default";
+  const tags = [...new Set([...(config.defaultTags ?? []), ...(input.tags ?? [])].map((tag) => tag.trim()).filter(Boolean))];
+  const click = cleanString(input.click ?? config.defaultClick, "click", { max: 1000 });
+  const url = ntfyTopicUrl(config);
+  const headers = ntfyHeaders({ config, title, priority, tags, click });
+
+  ensureNtfyChannelRegistered(config);
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), config.timeoutMs);
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers,
+      body,
+      signal: controller.signal,
+    });
+  } catch (error) {
+    if (controller.signal.aborted) throw new Error(`ntfy notify timed out after ${config.timeoutMs}ms`);
+    throw new Error(`ntfy notify failed: ${errMessage(error)}`);
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new Error(`ntfy notify failed: HTTP ${response.status}${text ? `: ${text.slice(0, 300)}` : ""}`);
+  }
+
+  return { ok: true, status: response.status, channelId: NTFY_CHANNEL_ID, topic: config.topic, priority, tags };
+}
+
+function normalizeNtfyConfig(value: unknown): NtfyChannelConfig {
+  if (!isRecord(value)) throw new ValidationError("ntfy channel config must be an object");
+  const timeoutMs = value.timeoutMs === undefined ? DEFAULT_NTFY_CONFIG.timeoutMs : value.timeoutMs;
+  if (typeof value.enabled !== "boolean") throw new ValidationError("ntfy.enabled must be a boolean");
+  if (typeof timeoutMs !== "number" || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1_000 || timeoutMs > 60_000) {
+    throw new ValidationError("ntfy.timeoutMs must be an integer between 1000 and 60000");
+  }
+  return {
+    enabled: value.enabled,
+    serverUrl: cleanString(value.serverUrl, "ntfy.serverUrl", { max: 500 }) ?? "",
+    topic: cleanString(value.topic, "ntfy.topic", { max: 200 }) ?? "",
+    tokenEnv: cleanString(value.tokenEnv, "ntfy.tokenEnv", { max: 120 }),
+    username: cleanString(value.username, "ntfy.username", { max: 120 }),
+    passwordEnv: cleanString(value.passwordEnv, "ntfy.passwordEnv", { max: 120 }),
+    defaultTags: cleanStringArray(value.defaultTags, "ntfy.defaultTags", { itemMax: 40, maxItems: 20 }) ?? [],
+    defaultClick: cleanString(value.defaultClick, "ntfy.defaultClick", { max: 1000 }),
+    timeoutMs,
+  };
+}
+
+function validateSendConfig(config: NtfyChannelConfig): void {
+  if (!config.enabled) throw new ValidationError("ntfy channel is disabled");
+  if (!config.serverUrl || !config.topic) {
+    throw new ValidationError("ntfy channel requires channel-type/ntfy serverUrl and topic");
+  }
+  if (config.topic.includes("/") || config.topic.includes("?") || config.topic.includes("#")) {
+    throw new ValidationError("ntfy.topic must be a single topic name, not a path or URL");
+  }
+  if (config.tokenEnv && (config.username || config.passwordEnv)) {
+    throw new ValidationError("ntfy auth must use tokenEnv or username/passwordEnv, not both");
+  }
+  if (config.passwordEnv && !config.username) throw new ValidationError("ntfy.username required when passwordEnv is set");
+}
+
+function ntfyTopicUrl(config: NtfyChannelConfig): string {
+  let base: URL;
+  try {
+    base = new URL(config.serverUrl.endsWith("/") ? config.serverUrl : `${config.serverUrl}/`);
+  } catch {
+    throw new ValidationError("ntfy.serverUrl must be a valid URL");
+  }
+  return new URL(encodeURIComponent(config.topic), base).toString();
+}
+
+function ntfyHeaders(input: {
+  config: NtfyChannelConfig;
+  title: string;
+  priority: NtfyPriority;
+  tags: string[];
+  click?: string;
+}): Record<string, string> {
+  const headers: Record<string, string> = {
+    Title: input.title,
+    Priority: String(priorityValue(input.priority)),
+  };
+  if (input.tags.length) headers.Tags = input.tags.join(",");
+  if (input.click) headers.Click = input.click;
+  const authorization = authHeader(input.config);
+  if (authorization) headers.Authorization = authorization;
+  return headers;
+}
+
+function authHeader(config: NtfyChannelConfig): string | undefined {
+  if (config.tokenEnv) {
+    const token = cleanString(process.env[config.tokenEnv], config.tokenEnv, { required: true, max: 4_000 })!;
+    return `Bearer ${token}`;
+  }
+  if (config.username && config.passwordEnv) {
+    const password = cleanString(process.env[config.passwordEnv], config.passwordEnv, { required: true, max: 4_000 })!;
+    return `Basic ${Buffer.from(`${config.username}:${password}`).toString("base64")}`;
+  }
+  return undefined;
+}
+
+function priorityValue(priority: NtfyPriority): number {
+  return NTFY_PRIORITIES.indexOf(priority) + 1;
+}
+
+function ensureNtfyChannelRegistered(config: NtfyChannelConfig): void {
+  upsertAgent({
+    id: NTFY_CHANNEL_ID,
+    name: "ntfy",
+    kind: "channel",
+    tags: ["channel", "ntfy", "channel:ntfy"],
+    capabilities: ["channel", "ntfy", "notify"],
+    status: "online",
+    ready: true,
+    meta: {
+      kind: "channel",
+      provider: "ntfy",
+      accountId: "default",
+      channelType: "ntfy",
+      transport: "ntfy",
+      direction: "outbound",
+      displayName: "ntfy",
+      topicChannels: [config.topic],
+    },
+  });
+}

package/src/quota-advisory.ts

@@ -29,6 +29,7 @@ type AgentRecipientRow = {
 };
 
 const RESET_ROUNDING_PERCENT = 99;
+const QUOTA_THRESHOLD_EPSILON = 1e-9;
 
 export function installQuotaAdvisoryHandler(): void {
   setProviderQuotaAdvisoryHandler(handleProviderQuotaAdvisory);
@@ -62,14 +63,14 @@ function handleProviderQuotaAdvisory(input: ProviderQuotaAdvisoryInput): string
       continue;
     }
 
-    if (remaining > config.warnRemaining) {
+    if (remaining - config.warnRemaining > QUOTA_THRESHOLD_EPSILON) {
       if (previous) delete nextState[window.name];
       continue;
     }
 
     const band = quotaRemainingBand(remaining, config.bandSize);
     if (previous?.lastQuotaAdvisoryBand === band) continue;
-    const stage: QuotaAdvisoryStage = remaining <= config.criticalRemaining ? "critical" : "warn";
+    const stage: QuotaAdvisoryStage = remaining - config.criticalRemaining <= QUOTA_THRESHOLD_EPSILON ? "critical" : "warn";
     notifyQuotaAdvisory({
       provider: input.provider,
       accountKey: input.accountKey,

package/src/quota-threshold-config.ts

@@ -4,7 +4,7 @@ import type { NotificationsConfig } from "./types";
 
 export const DEFAULT_QUOTA_THRESHOLD_CONFIG: NotificationsConfig["quotaThreshold"] = {
   enabled: true,
-  warnRemaining: 0.25,
+  warnRemaining: 0.15,
   criticalRemaining: 0.1,
   resetRemaining: 0.99,
   bandSize: 0.05,

package/src/routes/index.ts

@@ -6,7 +6,7 @@ import { deleteMyAvatar, deleteUserAvatarById, getMe, getUserAvatar, getUsers, h
 import { deleteArtifactById, getArtifactById, getArtifactContent, getArtifacts, headArtifactContent, postArtifact } from "./artifacts";
 import { deleteAutomationById, getAutomationById, getAutomationRuns, getAutomations, patchAutomation, postAutomation, postAutomationRun } from "./automations";
 import { deleteCommandById, deleteProviderModelRoute, getProviderConfigRoute, getProviderConfigsRoute, getProvidersRoute, patchProviderModelRoute, postProviderConfigTestRoute, putProviderConfigRoute, putProviderModelRoute } from "./provider-config";
-import { getProviderQuotasRoute, postProviderQuotaLeaseAcquireRoute, postProviderQuotaLeaseReleaseRoute, postProviderQuotaRoute } from "./provider-quotas";
+import { getProviderQuotasRoute, postProviderQuotaLeaseAcquireRoute, postProviderQuotaLeaseReleaseRoute, postProviderQuotaPublisherLeaseAcquireRoute, postProviderQuotaPublisherLeaseReleaseRoute, postProviderQuotaRoute } from "./provider-quotas";
 import { getProviderQuotaConfigRoute, getProviderQuotaConfigsRoute, putProviderQuotaConfigRoute } from "./provider-quota-config";
 import { getTeamsConfigRoute, putTeamsConfigRoute } from "./teams-config";
 import { deleteConfigKey, getConfigKey, getConfigKeyHistory, getConfigNamespace, putConfigKey } from "./config";
@@ -14,7 +14,7 @@ import { deleteInboxDraftRoute, getChatHistoryImportsRoute, getInboxStateRoute,
 import { deleteMemoryRoute, getMemories, getMemoryBrokerInfo, getMemoryById, getMemoryStats, patchMemory, postMemory, postMemoryInject, postMemorySearch } from "./memory";
 import { deleteMessageById, getCursorRoute, getMessageById, getMessageDeliveryRoute, getMessageStatusRoute, getMessageThread, getMessages, getQueuedMessagesRoute, patchMessage, postClaimMessage, postMessage, postMessageDeliveryAction, postMessageDeliveryAttempt, postMessageReaction, postRenewMessageClaim, postSystemBroadcast } from "./messages";
 import { deleteOrchestratorById, getOrchestratorById, getOrchestrators, patchOrchestratorAgents, postOrchestrator, postOrchestratorAction, postOrchestratorHeartbeat } from "./orchestrator";
-import { deleteSpawnPolicyRoute, getSpawnPoliciesHealth, getSpawnPoliciesRoute, getSpawnPolicyHealth, getSpawnPolicyRoute, getSpawnPolicyStatus, postSpawnPolicyRestart, postSpawnPolicyStart, postSpawnPolicyStop, putSpawnPolicyRoute } from "./spawn-policy";
+import { deleteSpawnPolicyRoute, getSpawnPoliciesHealth, getSpawnPoliciesRoute, getSpawnPolicyDiagnostics, getSpawnPolicyHealth, getSpawnPolicyRoute, getSpawnPolicyStatus, postSpawnPolicyRestart, postSpawnPolicyStart, postSpawnPolicyStop, putSpawnPolicyRoute } from "./spawn-policy";
 import { deleteTokenProfileRoute, getTokenById, getTokenMe, getTokenProfiles, getTokens, patchTokenProfile, postIntegrationRuntimeToken, postInteractiveRunnerRuntimeToken, postMcpRuntimeToken, postOrchestratorRunnerToken, postRuntimeTokenRenew, postToken, postTokenProfile, postTokenRevoke } from "./tokens";
 import { deleteWorkspaceById, getWorkspaceById, getWorkspaceDiagnostics, getWorkspaceDiff, getWorkspaceGitState, getWorkspaceMergePreview, getWorkspaceOrphans, getWorkspaceRecoveryBranches, getWorkspaceStewards, getWorkspaces, postWorkspaceAction, postWorkspaceCleanupStale, postWorkspaceOrphanReclaim, postWorkspaceRecoveryBranchDiscard } from "./workspaces";
 import { error, type Handler } from "./_shared";
@@ -112,6 +112,8 @@ const routes: Route[] = [
   route("POST", "/api/route", postRouteAdvice),
   route("GET", "/api/provider-quotas", getProviderQuotasRoute),
   route("POST", "/api/provider-quotas", postProviderQuotaRoute),
+  route("POST", "/api/provider-quota-leases/acquire", postProviderQuotaPublisherLeaseAcquireRoute),
+  route("POST", "/api/provider-quota-leases/release", postProviderQuotaPublisherLeaseReleaseRoute),
   route("POST", "/api/orchestrators/:id/provider-quota-leases/acquire", postProviderQuotaLeaseAcquireRoute),
   route("POST", "/api/orchestrators/:id/provider-quota-leases/release", postProviderQuotaLeaseReleaseRoute),
   route("GET", "/api/agents/spawn/directories", getHostDirectories),
@@ -259,6 +261,7 @@ const routes: Route[] = [
   route("GET", "/api/spawn-policies/health", getSpawnPoliciesHealth),
   route("GET", "/api/spawn-policy/:name/status", getSpawnPolicyStatus),
   route("GET", "/api/spawn-policy/:name/health", getSpawnPolicyHealth),
+  route("GET", "/api/spawn-policy/:name/diagnostics", getSpawnPolicyDiagnostics),
   route("GET", "/api/providers", getProvidersRoute),
   route("GET", "/api/providers/config", getProviderConfigsRoute),
   route("GET", "/api/providers/quota-config", getProviderQuotaConfigsRoute),

package/src/routes/provider-quotas.ts

@@ -66,6 +66,56 @@ function cleanLeaseBody(body: unknown): {
   return { provider, accountKey, ...(leaseToken ? { leaseToken } : {}), ttlMs };
 }
 
+function cleanPublisherLeaseBody(body: unknown): {
+  provider: string;
+  accountKey: string;
+  sourceAgentId: string;
+  leaseToken?: string;
+  ttlMs: number;
+} | string {
+  const input = cleanLeaseBody(body);
+  if (typeof input === "string") return input;
+  if (!isRecord(body)) return "JSON object body required";
+  const sourceAgentId = cleanString(body.sourceAgentId, "sourceAgentId", { required: true, max: 200 })!;
+  return { ...input, sourceAgentId };
+}
+
+const runnerLeaseHolderId = (sourceAgentId: string) => `runner:${sourceAgentId}`;
+
+export const postProviderQuotaPublisherLeaseAcquireRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const input = cleanPublisherLeaseBody(parsed.body);
+  if (typeof input === "string") return error(input);
+  const denied = authorizeRoute(req, { scope: "quota:write", resource: { agentId: input.sourceAgentId } });
+  if (denied) return denied;
+  return json(acquireProviderQuotaLease({
+    provider: input.provider,
+    accountKey: input.accountKey,
+    orchestratorId: runnerLeaseHolderId(input.sourceAgentId),
+    leaseToken: input.leaseToken,
+    ttlMs: input.ttlMs,
+  }));
+};
+
+export const postProviderQuotaPublisherLeaseReleaseRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const input = cleanPublisherLeaseBody(parsed.body);
+  if (typeof input === "string") return error(input);
+  if (!input.leaseToken) return error("leaseToken required");
+  const denied = authorizeRoute(req, { scope: "quota:write", resource: { agentId: input.sourceAgentId } });
+  if (denied) return denied;
+  return json({
+    released: releaseProviderQuotaLease({
+      provider: input.provider,
+      accountKey: input.accountKey,
+      orchestratorId: runnerLeaseHolderId(input.sourceAgentId),
+      leaseToken: input.leaseToken,
+    }),
+  });
+};
+
 export const postProviderQuotaLeaseAcquireRoute: Handler = async (req, params) => {
   const orch = getOrchestrator(params.id!);
   if (!orch) return error("orchestrator not found", 404);

package/src/routes/spawn-policy.ts

@@ -1,6 +1,6 @@
 // Auto-split from routes.ts (#299). Domain: spawn-policy.
-import { ValidationError, getOrchestrator } from "../db";
-import { auditEvent, authAuditMetadata, dashboardAttribution, emitCommand, error, json, parseBody, spawnRequestId, type Handler } from "./_shared";
+import { ValidationError, getCrashReport, getManagedPolicyTimeline, getOrchestrator } from "../db";
+import { auditEvent, authAuditMetadata, dashboardAttribution, emitCommand, error, json, parseBody, parseQueryInt, spawnRequestId, type Handler } from "./_shared";
 import { buildManagedSpawnParams } from "../managed-policy";
 import { cleanString } from "../validation";
 import { createCommand } from "../commands-db";
@@ -229,3 +229,20 @@ export const getSpawnPolicyHealth: Handler = (_req, params) => {
   const entry = getSpawnPolicy(params.name!);
   return entry ? json(policyStatusPayload(entry.value)) : error("spawn policy not found", 404);
 };
+
+export const getSpawnPolicyDiagnostics: Handler = (req, params) => {
+  const entry = getSpawnPolicy(params.name!);
+  if (!entry) return error("spawn policy not found", 404);
+  const url = new URL(req.url);
+  const limitRaw = parseQueryInt(url.searchParams.get("limit"), { min: 1, max: 200, clamp: true });
+  if (Number.isNaN(limitRaw)) return error("limit must be an integer between 1 and 200");
+  const sinceRaw = parseQueryInt(url.searchParams.get("since"), { min: 0, max: Number.MAX_SAFE_INTEGER });
+  if (Number.isNaN(sinceRaw)) return error("since must be a non-negative integer");
+  const status = policyStatusPayload(entry.value);
+  const agentId = typeof status.state.agentId === "string" ? status.state.agentId : undefined;
+  return json({
+    ...status,
+    timeline: getManagedPolicyTimeline(entry.value.name, { limit: limitRaw ?? 100, since: sinceRaw ?? undefined }),
+    crashReport: agentId ? getCrashReport(agentId) : null,
+  });
+};

package/src/security.ts

@@ -195,6 +195,8 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname.startsWith("/api/maintenance")) return "system:admin";
   if (pathname.startsWith("/api/tasks")) return method === "GET" ? "task:read" : "task:write";
   if (pathname.startsWith("/api/pairs")) return method === "GET" ? "pairs:read" : "pairs:write";
+  if (pathname === "/api/provider-quota-leases/acquire" || pathname === "/api/provider-quota-leases/release") return "quota:write";
+  if (pathname === "/api/provider-quotas") return method === "GET" ? "agent:read" : "quota:write";
   if (pathname === "/api/teams/config") return method === "GET" ? "teams:read" : "settings:write:teams";
   if (pathname.startsWith("/api/teams")) return method === "GET" ? "teams:read" : "teams:write";
   if (pathname.startsWith("/api/blackboard")) return method === "GET" ? "blackboard:read" : "blackboard:write";
@@ -277,6 +279,7 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   // Spawn requires the spawn capability (see requiredScopeFor above) — matches the in-service gate.
   if (pathname === "/api/agents/spawn") return "command:spawn";
   if (pathname.startsWith("/api/agents")) return method === "GET" ? "agent:read" : "agent:write";
+  if (pathname === "/api/provider-quota-leases/acquire" || pathname === "/api/provider-quota-leases/release") return "quota:write";
   if (pathname === "/api/provider-quotas") return method === "GET" ? "agent:read" : "quota:write";
   // Per-provider quota config (#605): reads are agent:read (the orchestrator
   // collector reads its config each tick); writes are settings:write:provider.