agent-relay-server 0.79.0 → 0.80.0

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.79.0",
+    "version": "0.80.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",
@@ -3332,6 +3332,60 @@
         ]
       }
     },
+    "/api/teams/config": {
+      "get": {
+        "operationId": "getTeamsConfigRoute",
+        "summary": "Get Teams Config",
+        "tags": [
+          "Other"
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      },
+      "put": {
+        "operationId": "putTeamsConfigRoute",
+        "summary": "Put Teams Config",
+        "tags": [
+          "Other"
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
     "/api/teams": {
       "get": {
         "operationId": "getTeamsRoute",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.79.0",
+  "version": "0.80.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.59",
+    "agent-relay-sdk": "0.2.60",
     "ajv": "^8.20.0"
   },
   "scripts": {

package/src/db/teams.ts

@@ -3,6 +3,7 @@ import { getAgent, setAgentTeam } from "./agents.ts";
 import { getDb, ValidationError } from "./connection.ts";
 import { rowToAgent } from "./mappers.ts";
 import { unpromotedBlackboardEntries, type UnpromotedBlackboardSummary } from "./project-entries.ts";
+import { isProviderBlocked } from "../provider-state.ts";
 import type { AgentCard, Team } from "../types";
 
 interface TeamRow {
@@ -72,6 +73,11 @@ export interface TeamOutcomeAggregates {
   recent: TeamOutcomeRecent[];
 }
 
+interface TeamBusyState {
+  busyMemberIds: string[];
+  lastBusyAt?: number;
+}
+
 export function teamId(): string {
   return `team_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
 }
@@ -132,6 +138,18 @@ export function countLiveTeamMembers(teamId: string, cutoff: number): number {
   return row.n;
 }
 
+export function getTeamBusyState(teamId: string, cutoff: number): TeamBusyState {
+  const rows = (getDb().query(
+    "SELECT * FROM agents WHERE team_id = ? AND status = 'busy' AND last_seen > ? ORDER BY last_seen DESC, id ASC",
+  ).all(teamId, cutoff) as any[])
+    .map(rowToAgent)
+    .filter((agent) => !isProviderBlocked(agent));
+  return {
+    busyMemberIds: rows.map((row) => row.id),
+    ...(rows[0] ? { lastBusyAt: rows[0].lastSeen } : {}),
+  };
+}
+
 export function setTeamZeroMembersSince(teamId: string, ts: number): boolean {
   return getDb().query("UPDATE teams SET zero_members_since = ?, updated_at = ? WHERE id = ?").run(ts, ts, teamId).changes > 0;
 }

package/src/maintenance/jobs.ts

@@ -51,7 +51,7 @@ import {
 } from "./constants";
 import { emitCommand } from "./events";
 import { reapOrphanedSessions } from "./orphaned-sessions";
-import { reapZeroMemberTeams } from "./teams";
+import { reapZeroMemberTeams, runTeamIdleWatchdog } from "./teams";
 import { scanWorkspaceConflicts, workspaceGC } from "./workspaces";
 import type { MaintenanceJobDefinition } from "./types";
 
@@ -208,6 +208,14 @@ export const definitions: MaintenanceJobDefinition[] = [
     runOnStart: false,
     handler: reapZeroMemberTeams,
   },
+  {
+    id: "team-idle-watchdog",
+    title: "Team idle watchdog",
+    description: "Gently ping a team's current coordinator once when the team has had no busy members for the configured threshold.",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: false,
+    handler: runTeamIdleWatchdog,
+  },
   {
     id: "orchestrator-reaper",
     title: "Orchestrator reaper",

package/src/maintenance/teams.ts

@@ -2,12 +2,134 @@ import {
   clearTeamZeroMembersSince,
   countLiveTeamMembers,
   createActivityEvent,
+  getTeamBusyState,
+  getTeamRoster,
   listActiveTeams,
   setTeamZeroMembersSince,
 } from "../db";
 import { STALE_TTL_MS } from "../config";
+import { agentProviderState } from "../provider-state";
 import { dissolveTeamById } from "../services/team";
+import { getTeamsConfig } from "../teams-config-store";
 import { teamReapGraceMs } from "./constants";
+import { notifyTarget } from "./events";
+
+interface TeamIdleTrackerEntry {
+  firstNoBusyAt: number;
+  pinged: boolean;
+}
+
+const teamIdleTracker = new Map<string, TeamIdleTrackerEntry>();
+
+export function resetTeamIdleWatchdogForTests(): void {
+  teamIdleTracker.clear();
+}
+
+function teamIdlePayload(teamId: string, coordinatorId: string, thresholdMinutes: number, idleForMs: number, firstNoBusyAt: number) {
+  const roster = getTeamRoster(teamId).map((member) => {
+    const providerState = agentProviderState(member);
+    return {
+      id: member.id,
+      name: member.name,
+      label: member.label,
+      status: member.status,
+      ready: member.ready,
+      lastSeen: member.lastSeen,
+      blocked: providerState?.state === "blocked",
+      providerState: providerState ?? undefined,
+    };
+  });
+  return {
+    kind: "team.idle",
+    teamId,
+    coordinatorId,
+    thresholdMinutes,
+    thresholdMs: thresholdMinutes * 60_000,
+    idleForMs,
+    firstNoBusyAt,
+    roster,
+    blockedMembers: roster.filter((member) => member.blocked).map((member) => ({
+      id: member.id,
+      providerState: member.providerState,
+    })),
+  };
+}
+
+function notifyTeamIdle(teamId: string, coordinatorId: string, thresholdMinutes: number, idleForMs: number, firstNoBusyAt: number): string | null {
+  const roundedIdleMinutes = Math.max(thresholdMinutes, Math.floor(idleForMs / 60_000));
+  const payload = teamIdlePayload(teamId, coordinatorId, thresholdMinutes, idleForMs, firstNoBusyAt);
+  return notifyTarget(
+    "team.idle",
+    { teamId, agentId: coordinatorId },
+    coordinatorId,
+    "Team idle watchdog",
+    `Team \`${teamId}\` has had no busy members for ${roundedIdleMinutes} min. If the work is done, stand down. If not, check the team roster and restart unfinished work.`,
+    payload,
+  );
+}
+
+export function runTeamIdleWatchdog(input: { now?: number } = {}): Record<string, unknown> {
+  const config = getTeamsConfig();
+  if (!config.enabled) {
+    const cleared = teamIdleTracker.size;
+    teamIdleTracker.clear();
+    return { enabled: false, clearedTrackedTeams: cleared };
+  }
+
+  const now = input.now ?? Date.now();
+  const cutoff = now - STALE_TTL_MS;
+  const thresholdMs = config.thresholdMinutes * 60_000;
+  const seen = new Set<string>();
+  const busyTeamIds: string[] = [];
+  const waitingTeamIds: string[] = [];
+  const pingedTeamIds: string[] = [];
+  const alreadyPingedTeamIds: string[] = [];
+  const missingCoordinatorTeamIds: string[] = [];
+
+  for (const team of listActiveTeams()) {
+    seen.add(team.id);
+    const busy = getTeamBusyState(team.id, cutoff);
+    if (busy.busyMemberIds.length > 0) {
+      teamIdleTracker.delete(team.id);
+      busyTeamIds.push(team.id);
+      continue;
+    }
+
+    const entry = teamIdleTracker.get(team.id) ?? { firstNoBusyAt: now, pinged: false };
+    teamIdleTracker.set(team.id, entry);
+    const idleForMs = now - entry.firstNoBusyAt;
+    if (idleForMs < thresholdMs) {
+      waitingTeamIds.push(team.id);
+      continue;
+    }
+
+    if (entry.pinged) {
+      alreadyPingedTeamIds.push(team.id);
+      continue;
+    }
+    if (!team.coordinatorId) {
+      missingCoordinatorTeamIds.push(team.id);
+      continue;
+    }
+
+    notifyTeamIdle(team.id, team.coordinatorId, config.thresholdMinutes, idleForMs, entry.firstNoBusyAt);
+    entry.pinged = true;
+    pingedTeamIds.push(team.id);
+  }
+
+  for (const key of teamIdleTracker.keys()) if (!seen.has(key)) teamIdleTracker.delete(key);
+
+  return {
+    enabled: true,
+    thresholdMinutes: config.thresholdMinutes,
+    trackedTeams: teamIdleTracker.size,
+    busyTeamIds,
+    waitingTeamIds,
+    pingedTeamIds,
+    alreadyPingedTeamIds,
+    missingCoordinatorTeamIds,
+  };
+}
 
 export function reapZeroMemberTeams(): Record<string, unknown> {
   const now = Date.now();

package/src/notification-types.ts

@@ -10,6 +10,7 @@ export type NotificationType =
   | "agent.resume_budget_exhausted"
   | "agent.transient_land_hold"
   | "agent.rate_limit_resume"
+  | "team.idle"
   | "plan.bound_agent_exited"
   | "workspace.steward_task"
   | "workspace.conflict"
@@ -60,6 +61,7 @@ export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
   "agent.resume_budget_exhausted": null,
   "agent.transient_land_hold": null,
   "agent.rate_limit_resume": 15 * MINUTES,
+  "team.idle": null,
   "plan.bound_agent_exited": null,
   "workspace.steward_task": null,
   "workspace.conflict": null,

package/src/routes/index.ts

@@ -7,6 +7,7 @@ import { deleteAutomationById, getAutomationById, getAutomationRuns, getAutomati
 import { deleteCommandById, deleteProviderModelRoute, getProviderConfigRoute, getProviderConfigsRoute, getProvidersRoute, patchProviderModelRoute, postProviderConfigTestRoute, putProviderConfigRoute, putProviderModelRoute } from "./provider-config";
 import { getProviderQuotasRoute, postProviderQuotaLeaseAcquireRoute, postProviderQuotaLeaseReleaseRoute, 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";
 import { deleteInboxDraftRoute, getChatHistoryImportsRoute, getInboxStateRoute, patchInboxThreadState, postChatHistoryImportRoute, putInboxDraft } from "./inbox";
 import { deleteMemoryRoute, getMemories, getMemoryBrokerInfo, getMemoryById, getMemoryStats, patchMemory, postMemory, postMemoryInject, postMemorySearch } from "./memory";
@@ -161,6 +162,8 @@ const routes: Route[] = [
   route("GET", "/api/merges/pauses/:id", getMergePauseById),
 
   route("POST", "/api/system/broadcast", postSystemBroadcast),
+  route("GET", "/api/teams/config", getTeamsConfigRoute),
+  route("PUT", "/api/teams/config", putTeamsConfigRoute),
   route("GET", "/api/teams", getTeamsRoute),
   route("GET", "/api/teams/outcomes", getTeamOutcomesRoute),
   route("GET", "/api/teams/me", getMyTeamRoute),

package/src/routes/teams-config.ts

@@ -0,0 +1,15 @@
+import { getTeamsConfig, setTeamsConfig } from "../teams-config-store";
+import { cleanString } from "../validation";
+import { error, json, parseBody, type Handler } from "./_shared";
+import { isRecord } from "agent-relay-sdk";
+
+export const getTeamsConfigRoute: Handler = () => {
+  return json(getTeamsConfig());
+};
+
+export const putTeamsConfigRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const updatedBy = isRecord(parsed.body) ? cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 }) : undefined;
+  return json(setTeamsConfig(parsed.body, { updatedBy }));
+};

package/src/security.ts

@@ -194,6 +194,7 @@ 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/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";
   if (pathname.startsWith("/api/issue-associations")) return method === "GET" ? "issue:read" : "issue:write";
@@ -280,6 +281,7 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   if (pathname === "/api/providers/quota-config" || pathname.match(/^\/api\/providers\/[^/]+\/quota-config$/)) {
     return method === "GET" ? "agent:read" : "settings:write:provider";
   }
+  if (pathname === "/api/teams/config") return method === "GET" ? "teams:read" : "settings:write:teams";
   if (pathname.startsWith("/api/messages") || pathname.startsWith("/api/inbox")) return method === "GET" ? "message:read" : "message:send";
   if (pathname.startsWith("/api/agent-profiles")) return method === "GET" ? "agent:read" : "agent:write";
   if (pathname.startsWith("/api/tasks")) return method === "GET" ? "task:read" : "task:write";
@@ -304,7 +306,7 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   return "system:admin";
 }
 
-const CONFIG_SETTINGS_NAMESPACES = new Set(["steward", "insights", "notifications", "workspace", "landing", "provider"]);
+const CONFIG_SETTINGS_NAMESPACES = new Set(["steward", "insights", "notifications", "workspace", "landing", "provider", "teams"]);
 
 function requiredSettingsScopeFor(method: string, pathname: string): string | null | undefined {
   if (pathname === "/api/settings") return method === "GET" ? "settings:read" : null;

package/src/settings/registry.ts

@@ -20,11 +20,14 @@ import {
   APPROVAL_MODES,
   errMessage,
   SPAWN_PROVIDERS,
+  TEAM_IDLE_THRESHOLD_MINUTES_MAX,
+  TEAM_IDLE_THRESHOLD_MINUTES_MIN,
   VALID_EFFORTS,
   type JSONSchema,
   type SettingDescriptor,
   type SettingScope,
 } from "agent-relay-sdk";
+import { DEFAULT_TEAMS_CONFIG } from "agent-relay-sdk/teams-config";
 
 /** Fail-closed default scope — a descriptor that omits scope requires admin to
  *  read and write (#385 owns the scope grammar; this layer only declares it). */
@@ -215,6 +218,20 @@ const WORKSPACE_SCHEMA: JSONSchema = {
   },
 };
 
+const TEAMS_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["enabled", "thresholdMinutes"],
+  properties: {
+    enabled: { type: "boolean" },
+    thresholdMinutes: {
+      type: "integer",
+      minimum: TEAM_IDLE_THRESHOLD_MINUTES_MIN,
+      maximum: TEAM_IDLE_THRESHOLD_MINUTES_MAX,
+    },
+  },
+};
+
 const LANDING_SCHEMA: JSONSchema = {
   type: "object",
   additionalProperties: false,
@@ -347,6 +364,16 @@ function seedBuiltInSettings(): void {
     display: { group: "Workspace", label: "Landing strategy", description: "Default land strategy for workspace branches.", order: 41 },
   });
 
+  registerSetting({
+    namespace: "teams",
+    key: "default",
+    schema: TEAMS_SCHEMA,
+    defaults: DEFAULT_TEAMS_CONFIG,
+    scope: { read: "settings:read:teams", write: "settings:write:teams" },
+    tier: "server-runtime",
+    display: { group: "Teams", label: "Team idle watchdog", description: "Coordinator nudge when a team has no busy members.", order: 45 },
+  });
+
   registerSetting({
     namespace: "provider",
     key: "chatCaptureMode",

package/src/teams-config-store.ts

@@ -0,0 +1,22 @@
+import { getConfig, setConfig } from "./config-store";
+import { emitConfigChanged } from "./sse";
+import {
+  DEFAULT_TEAMS_CONFIG,
+  normalizeTeamsConfig,
+  type TeamsConfig,
+} from "agent-relay-sdk";
+
+const TEAMS_CONFIG_NAMESPACE = "teams";
+const TEAMS_CONFIG_KEY = "default";
+
+export function getTeamsConfig(): TeamsConfig {
+  const entry = getConfig<TeamsConfig>(TEAMS_CONFIG_NAMESPACE, TEAMS_CONFIG_KEY);
+  return entry ? normalizeTeamsConfig(entry.value) : { ...DEFAULT_TEAMS_CONFIG };
+}
+
+export function setTeamsConfig(value: unknown, opts: { updatedBy?: string } = {}): TeamsConfig {
+  const normalized = normalizeTeamsConfig(value);
+  const entry = setConfig(TEAMS_CONFIG_NAMESPACE, TEAMS_CONFIG_KEY, normalized, opts.updatedBy);
+  emitConfigChanged(entry.namespace, entry.key, entry.version);
+  return normalized;
+}