agent-relay-server 0.62.2 → 0.63.0

package/src/db/pairs.ts

@@ -18,6 +18,7 @@ import { getAgent, listAgents } from "./agents.ts";
 import { getDb } from "./connection.ts";
 import { rowToPair } from "./mappers.ts";
 import { sendMessage } from "./messages.ts";
+export { closeOpenPairsForAgent } from "./pair-maintenance.ts";
 import type {
   AgentCard,
   ActivityEvent,
@@ -81,24 +82,16 @@ import type {
   WorkspaceStatus,
 } from "../types";
 
-export const OPEN_PAIR_STATUSES = ["pending", "active"] as const;
-export const DEFAULT_PAIR_TTL_MS = 5 * 60_000;
-export const MAX_PAIR_TTL_MS = DAY_MS;
+const OPEN_PAIR_STATUSES = ["pending", "active"] as const;
+const DEFAULT_PAIR_TTL_MS = 5 * 60_000;
+const MAX_PAIR_TTL_MS = DAY_MS;
 
-export function expirePendingPairs(now: number = Date.now()): void {
+function expirePendingPairs(now: number = Date.now()): void {
   getDb().query("UPDATE pairs SET status = 'expired', updated_at = ?, ended_at = ? WHERE status = 'pending' AND expires_at <= ?")
     .run(now, now, now);
 }
 
-export function closeOpenPairsForAgent(agentId: string, now: number = Date.now()): void {
-  getDb().query(`
-    UPDATE pairs
-    SET status = 'ended', ended_at = ?, ended_by = ?, updated_at = ?
-    WHERE status IN ('pending', 'active') AND (requester_id = ? OR target_id = ?)
-  `).run(now, agentId, now, agentId, agentId);
-}
-
-export function getOpenPairForAgent(agentId: string): PairSession | null {
+function getOpenPairForAgent(agentId: string): PairSession | null {
   expirePendingPairs();
   const row = getDb().query(`
     SELECT * FROM pairs
@@ -109,15 +102,15 @@ export function getOpenPairForAgent(agentId: string): PairSession | null {
   return row ? rowToPair(row) : null;
 }
 
-export function pairParticipant(pair: PairSession, agentId: string): boolean {
+function pairParticipant(pair: PairSession, agentId: string): boolean {
   return pair.requesterId === agentId || pair.targetId === agentId;
 }
 
-export function pairPeer(pair: PairSession, agentId: string): string {
+function pairPeer(pair: PairSession, agentId: string): string {
   return pair.requesterId === agentId ? pair.targetId : pair.requesterId;
 }
 
-export function resolvePairTarget(target: string, requesterId: string): {
+function resolvePairTarget(target: string, requesterId: string): {
   ok: true;
   agent: AgentCard;
 } | {
@@ -153,7 +146,7 @@ export function resolvePairTarget(target: string, requesterId: string): {
   return { ok: true, agent: available[0]! };
 }
 
-export function pairSystemMessage(pair: PairSession, to: string, event: string, subject: string, body: string): Message {
+function pairSystemMessage(pair: PairSession, to: string, event: string, subject: string, body: string): Message {
   return sendMessage({
     from: "system",
     to,
@@ -321,4 +314,3 @@ export function sendPairMessage(id: string, input: PairMessageInput): { ok: true
   getDb().query("UPDATE pairs SET last_message_at = ?, updated_at = ? WHERE id = ?").run(now, now, id);
   return { ok: true, pair: getPair(id)!, message };
 }
-

package/src/db/plans.ts

@@ -30,7 +30,7 @@ interface PlanVersionRow {
   changed_at: number;
 }
 
-export interface PlanVersionEntry {
+interface PlanVersionEntry {
   id: number;
   planId: string;
   version: number;

package/src/db/policy-runtime.ts

@@ -0,0 +1,14 @@
+import { getDb } from "./connection.ts";
+
+export function runningAgentForPolicy(policyName: string): string | null {
+  const row = getDb().query(`
+    SELECT s.agent_id
+    FROM managed_agent_state s
+    JOIN agents a ON a.id = s.agent_id
+    WHERE s.policy_name = ?
+      AND s.status = 'running'
+      AND s.agent_id IS NOT NULL
+      AND a.status != 'offline'
+  `).get(policyName) as { agent_id?: string } | undefined;
+  return row?.agent_id ?? null;
+}

package/src/db/project-entries.ts

@@ -203,7 +203,7 @@ const BLACKBOARD_TO_PROJECT_KIND: Record<BlackboardEntryKind, ProjectEntryKind>
   ruled_out: "rule",
 };
 
-export interface PromoteBlackboardEntryInput {
+interface PromoteBlackboardEntryInput {
   blackboardEntryId: string;
   projectId: string;
 }

package/src/db/projects.ts

@@ -76,7 +76,7 @@ export function rootsForProject(id: string): ProjectRoot[] {
   return rows.map(rowToRoot);
 }
 
-export interface EnsureProjectInput {
+interface EnsureProjectInput {
   slug: string;
   title?: string;
   description?: string;
@@ -265,7 +265,7 @@ export function dependencies(projectId: string): string[] {
   return rows.map((row) => row.to_project);
 }
 
-export interface ResolveProjectEntriesOptions {
+interface ResolveProjectEntriesOptions {
   kind?: ProjectEntryKind;
   includeInactive?: boolean;
   /** When true (default), merge in entries from transitive `contains` ancestors,

package/src/db/shared.ts

@@ -0,0 +1,7 @@
+import { parseJson } from "../utils";
+
+export function parseStringArray(raw: string): string[] {
+  const parsed = parseJson<unknown>(raw, []);
+  if (!Array.isArray(parsed)) return [];
+  return parsed.filter((value): value is string => typeof value === "string");
+}

package/src/db/stats.ts

@@ -147,7 +147,7 @@ export type AnalyticsPeriod = keyof typeof ANALYTICS_PERIODS;
 // Conversation categories. Order is significant: a claimable/channel/pair message
 // is classified as such even when it is also a reply; only an otherwise-plain reply
 // counts as "Replies". Session/control/system rows are EXCLUDED (they're streams 2/mechanical).
-export const CONVERSATION_CATEGORIES = ["Chat", "Replies", "Channel", "Pair", "Work items"] as const;
+const CONVERSATION_CATEGORIES = ["Chat", "Replies", "Channel", "Pair", "Work items"] as const;
 export type ConversationCategory = (typeof CONVERSATION_CATEGORIES)[number];
 const CONVERSATION_CATEGORY_SQL = `
   CASE
@@ -162,7 +162,7 @@ const CONVERSATION_FILTER = `kind NOT IN ('session','control','system') AND from
 
 // Session-mirror event sub-types we surface as the "agent work" composition. (prompt
 // is counted in the user-interaction stream; notice is mechanical chatter.)
-export const WORK_TYPES = ["tool", "reasoning", "narration", "response"] as const;
+const WORK_TYPES = ["tool", "reasoning", "narration", "response"] as const;
 export type WorkType = (typeof WORK_TYPES)[number];
 
 export interface AnalyticsData {

package/src/db/task-core.ts

@@ -0,0 +1,18 @@
+import { getDb } from "./connection.ts";
+import { rowToTaskEvent } from "./mappers.ts";
+import type { TaskEvent } from "../types";
+
+export const TASK_SELECT = "SELECT * FROM tasks";
+
+export function insertTaskEvent(taskId: number, event: Required<Omit<TaskEvent, "id" | "taskId" | "createdAt">>, now: number): TaskEvent {
+  const result = getDb().query(`
+    INSERT INTO task_events (task_id, source, type, severity, title, body, metadata, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(taskId, event.source, event.type, event.severity, event.title, event.body, JSON.stringify(event.metadata), now);
+  return getTaskEvent(Number(result.lastInsertRowid))!;
+}
+
+function getTaskEvent(id: number): TaskEvent | null {
+  const row = getDb().query("SELECT * FROM task_events WHERE id = ?").get(id) as any;
+  return row ? rowToTaskEvent(row) : null;
+}

package/src/db/task-maintenance.ts

@@ -0,0 +1,24 @@
+import { getDb } from "./connection.ts";
+import { TASK_SELECT, insertTaskEvent } from "./task-core.ts";
+
+// On-demand automation tasks (targetMode=on_demand_agent) are bound to a single
+// ephemeral agent spawned just for that task. When that agent's claim is released,
+// the task must not return to a claimable pool that can never match it again.
+export function settleSingleTargetOnDemandTasks(condition: string, params: any[], now: number, reason: string): void {
+  const selectSql = `${TASK_SELECT} WHERE (${condition}) AND json_extract(metadata, '$.targetMode') = 'on_demand_agent' AND status IN ('claimed', 'in_progress', 'blocked', 'orphaned')`;
+  const rows = getDb().query(selectSql).all(...params) as any[];
+  if (rows.length === 0) return;
+  getDb().query(
+    `UPDATE tasks SET status = 'done', claim_expires_at = NULL, updated_at = ?, last_seen_at = ? WHERE (${condition}) AND json_extract(metadata, '$.targetMode') = 'on_demand_agent' AND status IN ('claimed', 'in_progress', 'blocked', 'orphaned')`
+  ).run(now, now, ...params);
+  for (const row of rows) {
+    insertTaskEvent(row.id, {
+      source: "agent-relay",
+      type: "task.auto-completed",
+      severity: row.severity,
+      title: "On-demand task auto-resolved",
+      body: `On-demand agent ${row.claimed_by ?? "(unknown)"} exited (${reason}); task resolved so it does not orphan`,
+      metadata: { agentId: row.claimed_by, reason, completedBy: "relay" },
+    }, now);
+  }
+}

package/src/db/tasks.ts

@@ -14,11 +14,13 @@ import {
 } from "../contracts";
 import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
 import { matchAgents } from "../agent-ref";
-import { getAgent, settleSingleTargetOnDemandTasks, validateAgentSession } from "./agents.ts";
+import { getAgent, validateAgentSession } from "./agents.ts";
 import { messageTaskClosed } from "./claim-sql.ts";
 import { ClaimError, getDb } from "./connection.ts";
 import { rowToTask, rowToTaskEvent } from "./mappers.ts";
-import { claimMessageRow } from "./messages.ts";
+import { claimMessageRow } from "./message-claims.ts";
+import { TASK_SELECT, insertTaskEvent } from "./task-core.ts";
+import { settleSingleTargetOnDemandTasks } from "./task-maintenance.ts";
 import type {
   AgentCard,
   ActivityEvent,
@@ -82,7 +84,7 @@ import type {
   WorkspaceStatus,
 } from "../types";
 
-export const TASK_SELECT = "SELECT * FROM tasks";
+export { TASK_SELECT, insertTaskEvent } from "./task-core.ts";
 
 export function findOpenTaskByDedupe(source: string, dedupeKey: string): Task | null {
   const row = getDb()
@@ -91,19 +93,6 @@ export function findOpenTaskByDedupe(source: string, dedupeKey: string): Task |
   return row ? rowToTask(row) : null;
 }
 
-export function insertTaskEvent(taskId: number, event: Required<Omit<TaskEvent, "id" | "taskId" | "createdAt">>, now: number): TaskEvent {
-  const result = getDb().query(`
-    INSERT INTO task_events (task_id, source, type, severity, title, body, metadata, created_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(taskId, event.source, event.type, event.severity, event.title, event.body, JSON.stringify(event.metadata), now);
-  return getTaskEvent(Number(result.lastInsertRowid))!;
-}
-
-export function getTaskEvent(id: number): TaskEvent | null {
-  const row = getDb().query("SELECT * FROM task_events WHERE id = ?").get(id) as any;
-  return row ? rowToTaskEvent(row) : null;
-}
-
 export function taskMessageBody(task: Pick<Task, "id" | "source" | "severity" | "body" | "externalUrl" | "dedupeKey">): string {
   const lines = [
     `[task:${task.id}] ${task.severity.toUpperCase()} from ${task.source}`,
@@ -405,4 +394,3 @@ export function listCallbackDeliveries(taskId: number): Array<{
 }
 
 // --- Pair sessions ---
-

package/src/db/teams.ts

@@ -26,7 +26,7 @@ interface TeamRow {
   dissolved_at: number | null;
 }
 
-export interface TeamDissolveInput {
+interface TeamDissolveInput {
   outcomeStatus?: Team["outcomeStatus"];
   outcomeSummary?: string;
   landsClean?: boolean;
@@ -53,7 +53,7 @@ export interface TeamOutcomeCompositionAggregate {
   avgWallClockMs: number | null;
 }
 
-export interface TeamOutcomeRecent {
+interface TeamOutcomeRecent {
   id: string;
   title?: string;
   outcome: Team["outcomeStatus"] | null;
@@ -274,7 +274,7 @@ export function getTeamOutcomeAggregates(input: { recentLimit?: number } = {}):
   };
 }
 
-export interface TeamDissolveResult {
+interface TeamDissolveResult {
   team: Team;
   /** Active blackboard findings not yet lifted into a project — surfaced (not auto-promoted)
    * so the operator/agent can decide what graduates to durable project knowledge (#404). */

package/src/db/workspaces.ts

@@ -78,7 +78,7 @@ import type {
   WorkspaceStatus,
 } from "../types";
 
-export function rowToWorkspace(row: any): WorkspaceRecord {
+function rowToWorkspace(row: any): WorkspaceRecord {
   return {
     id: row.id,
     repoRoot: row.repo_root,
@@ -266,7 +266,7 @@ export function pruneOrphanedSharedWorkspaces(): string[] {
 // owner's branch-state badge" (#236). A hook, not a direct emit, because getDb().ts is
 // the lowest layer — sse.ts imports db, so db can't import sse without a cycle. sse
 // registers a listener at startup that re-emits the owner agent's status over SSE.
-export type WorkspaceChangeListener = (workspace: WorkspaceRecord) => void;
+type WorkspaceChangeListener = (workspace: WorkspaceRecord) => void;
 export const workspaceChangeListeners = new Set<WorkspaceChangeListener>();
 export function onWorkspaceChange(listener: WorkspaceChangeListener): void {
   workspaceChangeListeners.add(listener);
@@ -322,9 +322,9 @@ export function setWorkspaceBranch(id: string, branch: string, baseSha?: string)
 
 // Workspace statuses that count as "live" for stewardship — an agent owning one
 // of these is a candidate steward; the repo is worth coordinating.
-export const STEWARD_LIVE_STATUSES = "'active', 'ready', 'conflict', 'review_requested', 'merge_planned'";
+const STEWARD_LIVE_STATUSES = "'active', 'ready', 'conflict', 'review_requested', 'merge_planned'";
 
-export interface RepoStewardRecord {
+interface RepoStewardRecord {
   repoRoot: string;
   stewardAgentId?: string;
   lastStewardAgentId?: string;
@@ -332,7 +332,7 @@ export interface RepoStewardRecord {
   updatedAt: number;
 }
 
-export function rowToRepoSteward(row: any): RepoStewardRecord {
+function rowToRepoSteward(row: any): RepoStewardRecord {
   return {
     repoRoot: row.repo_root,
     stewardAgentId: row.steward_agent_id ?? undefined,
@@ -354,7 +354,7 @@ export function listRepoStewards(): RepoStewardRecord[] {
 // Persist the elected steward for a repo. The row is never deleted, so a repo's
 // stewardship survives a full all-agents-offline gap (steward goes NULL/dormant,
 // last_steward_agent_id keeps continuity) and resumes on the next agent join.
-export function upsertRepoSteward(repoRoot: string, steward: string | null, now: number): void {
+function upsertRepoSteward(repoRoot: string, steward: string | null, now: number): void {
   getDb().query(`
     INSERT INTO repo_stewards (repo_root, steward_agent_id, last_steward_agent_id, elected_at, updated_at)
     VALUES ($repoRoot, $steward, $steward, $electedAt, $now)

package/src/issue-tracker/github.ts

@@ -2,7 +2,7 @@ import type { IssueRef, IssueRefStatus } from "../types";
 import type { IssueTrackerAdapter, IssueTrackerCloseOptions, IssueTrackerReopenOptions, IssueTrackerStatus } from "./adapter";
 
 export const GITHUB_FIXED_LABEL = "fixed";
-export const GITHUB_CREDENTIAL_REQUIREMENT = "GitHub issue tracker adapter requires gh authenticated with a token that has issues:write scope";
+const GITHUB_CREDENTIAL_REQUIREMENT = "GitHub issue tracker adapter requires gh authenticated with a token that has issues:write scope";
 
 type GitHubApiMethod = "GET" | "PATCH" | "POST";
 
@@ -12,7 +12,7 @@ export interface GitHubApiRequest {
   body?: Record<string, unknown>;
 }
 
-export type GitHubApi = (request: GitHubApiRequest) => Promise<unknown>;
+type GitHubApi = (request: GitHubApiRequest) => Promise<unknown>;
 
 interface GitHubIssuePayload {
   state?: unknown;
@@ -92,7 +92,7 @@ function uniqueLabels(labels: string[]): string[] {
   return [...new Set(labels.map((label) => label.trim()).filter(Boolean))];
 }
 
-export class GitHubIssueTrackerAdapter implements IssueTrackerAdapter {
+class GitHubIssueTrackerAdapter implements IssueTrackerAdapter {
   constructor(private readonly api: GitHubApi = ghApi) {}
 
   resolveLink(ref: IssueRef): string {

package/src/maintenance/constants.ts

@@ -0,0 +1,35 @@
+import { DAY_MS, REAP_INTERVAL_MS } from "../config";
+import { READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "../workspace-phase";
+import type { WorkspaceStatus } from "../types";
+
+export { DAY_MS, REAP_INTERVAL_MS, TERMINAL_WORKSPACE_STATUSES };
+
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const SCHEDULER_TICK_MS = 10_000;
+export const OUTBOX_RETENTION_MS = Number(process.env.AGENT_RELAY_OUTBOX_RETENTION_MS) || 60 * 60 * 1000;
+export const TOKEN_RECORD_RETENTION_SECONDS = Number(process.env.AGENT_RELAY_TOKEN_RECORD_RETENTION_SECONDS) || 7 * 24 * 60 * 60;
+export const CONFLICT_SCAN_INTERVAL_MS = Number(process.env.AGENT_RELAY_CONFLICT_SCAN_INTERVAL_MS) || 10 * 60 * 1000;
+export const WORKSPACE_RETENTION_MS = Number(process.env.AGENT_RELAY_WORKSPACE_RETENTION_MS) || DAY_MS;
+export const DB_MAINTENANCE_INTERVAL_MS = Number(process.env.AGENT_RELAY_DB_MAINTENANCE_INTERVAL_MS) || DAY_MS;
+export const DB_VACUUM_EVERY = Number(process.env.AGENT_RELAY_DB_VACUUM_EVERY) || 7;
+export const WORKSPACE_REVIEW_TTL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_REVIEW_TTL_MS) || 3 * DAY_MS;
+export const WORKSPACE_GC_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_GC_INTERVAL_MS) || 60 * 60 * 1000;
+export const WORKSPACE_ORPHAN_REAPER_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_ORPHAN_REAPER_INTERVAL_MS) || 30 * 60 * 1000;
+export const WORKSPACE_AUTO_MERGE_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_AUTO_MERGE_INTERVAL_MS) || CONFLICT_SCAN_INTERVAL_MS;
+export const ORPHAN_REAPER_INTERVAL_MS = Number(process.env.AGENT_RELAY_ORPHAN_REAPER_INTERVAL_MS) || 5 * 60 * 1000;
+
+export const stewardEscalationMs = () => Number(process.env.AGENT_RELAY_WORKSPACE_STEWARD_ESCALATION_MS) || 60 * 60 * 1000;
+export const stewardFallbackTarget = () => (process.env.AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK || "").trim();
+export const STRANDABLE_STATUSES = new Set<WorkspaceStatus>([...READY_TO_LAND_STATUSES, "conflict"]);
+export const CONFLICT_SCAN_STATUSES = new Set<WorkspaceStatus>(["active", "ready", "review_requested", "merge_planned", "conflict"]);
+export const LANDED_RECONCILE_STATUSES = new Set<WorkspaceStatus>(["merge_planned", "review_requested", "conflict"]);
+
+export const envMsOrDefault = (name: string, fallback: number): number => {
+  const v = Number(process.env[name]);
+  return Number.isFinite(v) && v >= 0 ? v : fallback;
+};
+export const orphanGraceMs = () => envMsOrDefault("AGENT_RELAY_ORPHAN_GRACE_MS", 30 * 60 * 1000);
+export const orphanReapCooldownMs = () => envMsOrDefault("AGENT_RELAY_ORPHAN_REAP_COOLDOWN_MS", 5 * 60 * 1000);
+export const teamReapGraceMs = () => envMsOrDefault("TEAM_REAP_GRACE_MS", 30 * 60 * 1000);
+export const teamReapIntervalMs = () => envMsOrDefault("TEAM_REAP_INTERVAL_MS", 5 * 60 * 1000);
+export const orphanReapEnabled = () => process.env.AGENT_RELAY_ORPHAN_REAP !== "0";

package/src/maintenance/events.ts

@@ -0,0 +1,32 @@
+import { emitRelayEvent } from "../events";
+import { routeNotification, type NotificationScope, type NotificationType } from "../notification-router";
+import type { Command } from "../types";
+
+export function emitCommand(command: Command): void {
+  const suffix = command.status === "timed_out" ? "timed_out" : command.status;
+  emitRelayEvent({
+    type: `command.${suffix}`,
+    source: command.source,
+    subject: command.id,
+    data: { command },
+  });
+}
+
+// Route a maintenance notification, swallowing failures (a stale/missing/misconfigured
+// target must never break the sweep). Returns the target on success, null otherwise.
+export function notifyTarget(
+  type: NotificationType,
+  scope: NotificationScope,
+  target: string,
+  subject: string,
+  body: string,
+  payload: Record<string, unknown>,
+): string | null {
+  if (!target) return null;
+  try {
+    routeNotification({ type, scope, recipients: [target], message: { subject, body, payload } });
+    return target;
+  } catch {
+    return null;
+  }
+}

package/src/maintenance/index.ts

@@ -0,0 +1,7 @@
+export {
+  listMaintenanceJobs,
+  resetOrphanTrackerForTests,
+  runLegacyMaintenanceReaper,
+  runMaintenanceJobNow,
+  startMaintenanceScheduler,
+} from "./scheduler";