@synth-deploy/server 0.1.0

package/src/agent/envoy-registry.ts

@@ -0,0 +1,384 @@
+import crypto from "node:crypto";
+import { EnvoyClient } from "./envoy-client.js";
+import type { EnvoyHealthResponse } from "./envoy-client.js";
+import type { PersistentEnvoyRegistryStore, PersistedEnvoyRegistration } from "@synth-deploy/core";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface EnvoyRegistration {
+  id: string;
+  name: string;
+  url: string;
+  /** Shared secret for authenticating requests between Command and this Envoy */
+  token: string;
+  /** Environments this Envoy is assigned to (empty = available for any) */
+  assignedEnvironments: string[];
+  /** Partitions this Envoy is assigned to */
+  assignedPartitions: string[];
+  registeredAt: string;
+  lastHealthCheck: string | null;
+  lastHealthStatus: "healthy" | "degraded" | "unreachable" | null;
+  /** Cached from last successful health probe */
+  cachedHostname: string | null;
+  cachedOs: string | null;
+  cachedSummary: EnvoyHealthResponse["summary"] | null;
+  cachedReadiness: EnvoyHealthResponse["readiness"] | null;
+}
+
+export interface EnvoyRegistryEntry extends EnvoyRegistration {
+  health: "OK" | "Degraded" | "Unreachable";
+  hostname: string | null;
+  os: string | null;
+  lastSeen: string | null;
+  summary: EnvoyHealthResponse["summary"] | null;
+  readiness: EnvoyHealthResponse["readiness"] | null;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers to convert between persisted and domain types
+// ---------------------------------------------------------------------------
+
+function fromPersisted(p: PersistedEnvoyRegistration): EnvoyRegistration {
+  return {
+    id: p.id,
+    name: p.name,
+    url: p.url,
+    token: p.token,
+    assignedEnvironments: p.assignedEnvironments,
+    assignedPartitions: p.assignedPartitions,
+    registeredAt: p.registeredAt,
+    lastHealthCheck: p.lastHealthCheck,
+    lastHealthStatus: p.lastHealthStatus,
+    cachedHostname: p.cachedHostname,
+    cachedOs: p.cachedOs,
+    cachedSummary: p.cachedSummary as EnvoyHealthResponse["summary"] | null,
+    cachedReadiness: p.cachedReadiness as EnvoyHealthResponse["readiness"] | null,
+  };
+}
+
+function toPersisted(r: EnvoyRegistration): PersistedEnvoyRegistration {
+  return {
+    id: r.id,
+    name: r.name,
+    url: r.url,
+    token: r.token,
+    assignedEnvironments: r.assignedEnvironments,
+    assignedPartitions: r.assignedPartitions,
+    registeredAt: r.registeredAt,
+    lastHealthCheck: r.lastHealthCheck,
+    lastHealthStatus: r.lastHealthStatus,
+    cachedHostname: r.cachedHostname,
+    cachedOs: r.cachedOs,
+    cachedSummary: r.cachedSummary,
+    cachedReadiness: r.cachedReadiness,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// EnvoyRegistry — SQLite-backed registry for multiple Envoy instances
+// ---------------------------------------------------------------------------
+
+export class EnvoyRegistry {
+  constructor(private store?: PersistentEnvoyRegistryStore) {}
+
+  /**
+   * Register a new Envoy. Returns the registration with a generated token.
+   */
+  register(params: {
+    name: string;
+    url: string;
+    assignedEnvironments?: string[];
+    assignedPartitions?: string[];
+  }): EnvoyRegistration {
+    const id = crypto.randomUUID();
+    const token = crypto.randomBytes(32).toString("hex");
+
+    const registration: EnvoyRegistration = {
+      id,
+      name: params.name,
+      url: params.url,
+      token,
+      assignedEnvironments: params.assignedEnvironments ?? [],
+      assignedPartitions: params.assignedPartitions ?? [],
+      registeredAt: new Date().toISOString(),
+      lastHealthCheck: null,
+      lastHealthStatus: null,
+      cachedHostname: null,
+      cachedOs: null,
+      cachedSummary: null,
+      cachedReadiness: null,
+    };
+
+    this.store?.insert(toPersisted(registration));
+    return registration;
+  }
+
+  /**
+   * Deregister an Envoy by ID.
+   */
+  deregister(id: string): boolean {
+    if (this.store) {
+      return this.store.delete(id);
+    }
+    return false;
+  }
+
+  /**
+   * List all registered Envoys.
+   */
+  list(): EnvoyRegistration[] {
+    if (this.store) {
+      return this.store.list().map(fromPersisted);
+    }
+    return [];
+  }
+
+  /**
+   * Update an Envoy's assignment or name.
+   */
+  update(id: string, updates: {
+    name?: string;
+    url?: string;
+    assignedEnvironments?: string[];
+    assignedPartitions?: string[];
+  }): EnvoyRegistration | undefined {
+    if (!this.store) return undefined;
+    const existing = this.store.getById(id);
+    if (!existing) return undefined;
+
+    this.store.update(id, {
+      name: updates.name,
+      url: updates.url,
+      assignedEnvironments: updates.assignedEnvironments,
+      assignedPartitions: updates.assignedPartitions,
+    });
+
+    return fromPersisted(this.store.getById(id)!);
+  }
+
+  /**
+   * Ensure an envoy at `url` is registered with a specific `token`.
+   * If already registered, updates its token. If not, creates a new entry.
+   * Used to bootstrap the default envoy from environment variables (SYNTH_ENVOY_TOKEN).
+   */
+  ensureRegisteredWithToken(params: { name: string; url: string }, token: string): EnvoyRegistration {
+    const existing = this.list().find((r) => r.url === params.url);
+    if (existing) {
+      this.store?.updateToken(existing.id, token);
+      return { ...existing, token };
+    }
+
+    const id = crypto.randomUUID();
+    const registration: EnvoyRegistration = {
+      id,
+      name: params.name,
+      url: params.url,
+      token,
+      assignedEnvironments: [],
+      assignedPartitions: [],
+      registeredAt: new Date().toISOString(),
+      lastHealthCheck: null,
+      lastHealthStatus: null,
+      cachedHostname: null,
+      cachedOs: null,
+      cachedSummary: null,
+      cachedReadiness: null,
+    };
+    this.store?.insert(toPersisted(registration));
+    return registration;
+  }
+
+  /**
+   * Rotate the token for an Envoy. Returns the new token.
+   */
+  rotateToken(id: string): string | undefined {
+    if (!this.store) return undefined;
+    const existing = this.store.getById(id);
+    if (!existing) return undefined;
+
+    const newToken = crypto.randomBytes(32).toString("hex");
+    this.store.updateToken(id, newToken);
+    return newToken;
+  }
+
+  /**
+   * Validate a token against a registered Envoy.
+   */
+  validateToken(token: string): EnvoyRegistration | undefined {
+    if (!this.store) return undefined;
+    const persisted = this.store.getByToken(token);
+    return persisted ? fromPersisted(persisted) : undefined;
+  }
+
+  /**
+   * Update health status for an Envoy (called after probing).
+   */
+  updateHealth(id: string, status: "healthy" | "degraded" | "unreachable"): void {
+    this.store?.updateHealth(id, status, new Date().toISOString());
+  }
+
+  /**
+   * Find the best Envoy for a given environment.
+   * Priority: assigned + healthy > assigned + degraded > unassigned + healthy > fallback
+   */
+  findForEnvironment(environmentName: string): EnvoyRegistration | undefined {
+    const all = this.list();
+    if (all.length === 0) return undefined;
+
+    // Assigned and healthy
+    const assignedHealthy = all.find(
+      (e) =>
+        e.assignedEnvironments.includes(environmentName) &&
+        e.lastHealthStatus === "healthy",
+    );
+    if (assignedHealthy) return assignedHealthy;
+
+    // Assigned (any status)
+    const assigned = all.find((e) =>
+      e.assignedEnvironments.includes(environmentName),
+    );
+    if (assigned) return assigned;
+
+    // Unassigned and healthy (available for any environment)
+    const unassignedHealthy = all.find(
+      (e) =>
+        e.assignedEnvironments.length === 0 &&
+        e.lastHealthStatus === "healthy",
+    );
+    if (unassignedHealthy) return unassignedHealthy;
+
+    // Unassigned (any status)
+    const unassigned = all.find((e) => e.assignedEnvironments.length === 0);
+    if (unassigned) return unassigned;
+
+    // Fallback: any envoy
+    return all[0];
+  }
+
+  /**
+   * Return cached registry entry without probing (instant).
+   */
+  get(id: string): EnvoyRegistryEntry | undefined {
+    if (!this.store) return undefined;
+    const persisted = this.store.getById(id);
+    if (!persisted) return undefined;
+    const reg = fromPersisted(persisted);
+    const healthMap: Record<string, "OK" | "Degraded" | "Unreachable"> = {
+      healthy: "OK",
+      degraded: "Degraded",
+      unreachable: "Unreachable",
+    };
+    return {
+      ...reg,
+      health: healthMap[reg.lastHealthStatus ?? "unreachable"] ?? "Unreachable",
+      hostname: reg.cachedHostname,
+      os: reg.cachedOs,
+      lastSeen: reg.lastHealthCheck,
+      summary: reg.cachedSummary,
+      readiness: reg.cachedReadiness,
+    };
+  }
+
+  /**
+   * Return all cached registry entries without probing (instant).
+   */
+  listEntries(): EnvoyRegistryEntry[] {
+    return this.list().map((reg) => {
+      const healthMap: Record<string, "OK" | "Degraded" | "Unreachable"> = {
+        healthy: "OK",
+        degraded: "Degraded",
+        unreachable: "Unreachable",
+      };
+      return {
+        ...reg,
+        health: healthMap[reg.lastHealthStatus ?? "unreachable"] ?? "Unreachable",
+        hostname: reg.cachedHostname,
+        os: reg.cachedOs,
+        lastSeen: reg.lastHealthCheck,
+        summary: reg.cachedSummary,
+        readiness: reg.cachedReadiness,
+      };
+    });
+  }
+
+  /**
+   * Probe an Envoy's health and update its registry entry.
+   */
+  async probe(id: string): Promise<EnvoyRegistryEntry | undefined> {
+    if (!this.store) return undefined;
+    const persisted = this.store.getById(id);
+    if (!persisted) return undefined;
+    const registration = fromPersisted(persisted);
+
+    const client = new EnvoyClient(registration.url, 5000);
+    try {
+      const health = await client.checkHealth();
+      const status = health.status === "healthy" ? "healthy" : "degraded";
+      const timestamp = new Date().toISOString();
+
+      this.store.updateCachedProbe(id, {
+        lastHealthCheck: timestamp,
+        lastHealthStatus: status,
+        cachedHostname: health.hostname,
+        cachedOs: health.os ?? null,
+        cachedSummary: health.summary,
+        cachedReadiness: health.readiness,
+      });
+
+      return {
+        ...registration,
+        lastHealthCheck: timestamp,
+        lastHealthStatus: status,
+        cachedHostname: health.hostname,
+        cachedOs: health.os ?? null,
+        cachedSummary: health.summary,
+        cachedReadiness: health.readiness,
+        health: status === "healthy" ? "OK" : "Degraded",
+        hostname: health.hostname,
+        os: health.os ?? null,
+        lastSeen: health.timestamp,
+        summary: health.summary,
+        readiness: health.readiness,
+      };
+    } catch {
+      const timestamp = new Date().toISOString();
+      this.store.updateCachedProbe(id, {
+        lastHealthCheck: timestamp,
+        lastHealthStatus: "unreachable",
+        cachedHostname: null,
+        cachedOs: null,
+        cachedSummary: null,
+        cachedReadiness: null,
+      });
+      return {
+        ...registration,
+        lastHealthCheck: timestamp,
+        lastHealthStatus: "unreachable",
+        cachedHostname: null,
+        cachedOs: null,
+        cachedSummary: null,
+        cachedReadiness: null,
+        health: "Unreachable",
+        hostname: null,
+        os: null,
+        lastSeen: null,
+        summary: null,
+        readiness: null,
+      };
+    }
+  }
+
+  /**
+   * Probe all registered Envoys and return their status.
+   */
+  async probeAll(): Promise<EnvoyRegistryEntry[]> {
+    const entries: EnvoyRegistryEntry[] = [];
+    for (const envoy of this.list()) {
+      const entry = await this.probe(envoy.id);
+      if (entry) entries.push(entry);
+    }
+    return entries;
+  }
+}

package/src/agent/health-checker.ts

@@ -0,0 +1,70 @@
+import { serverLog, serverWarn, serverError } from "../logger.js";
+
+/**
+ * Service health check abstraction.
+ *
+ * Injected into the Command Agent so tests can control health check outcomes
+ * without real network calls. In later phases, a real implementation will
+ * make HTTP calls to Envoy health endpoints.
+ */
+
+export interface HealthCheckResult {
+  reachable: boolean;
+  responseTimeMs: number | null;
+  error: string | null;
+}
+
+export interface ServiceHealthChecker {
+  /**
+   * Check if the target service/environment is healthy and reachable.
+   */
+  check(
+    serviceId: string,
+    context: { partitionId: string; environmentName: string },
+  ): Promise<HealthCheckResult>;
+}
+
+/**
+ * Default health checker — always reports healthy.
+ * Used in development and when no real infrastructure is connected.
+ */
+export class DefaultHealthChecker implements ServiceHealthChecker {
+  async check(): Promise<HealthCheckResult> {
+    return { reachable: true, responseTimeMs: 1, error: null };
+  }
+}
+
+/**
+ * Real health checker that makes HTTP requests to an Envoy health endpoint.
+ * Used when an Envoy URL is configured.
+ */
+export class EnvoyHealthChecker implements ServiceHealthChecker {
+  constructor(private readonly envoyUrl: string, private readonly timeoutMs = 5000) {}
+
+  async check(): Promise<HealthCheckResult> {
+    serverLog("HEALTH-CHECK", { url: this.envoyUrl });
+    const start = Date.now();
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+      const res = await fetch(`${this.envoyUrl}/health`, { signal: controller.signal });
+      clearTimeout(timeout);
+      const responseTimeMs = Date.now() - start;
+
+      if (res.ok) {
+        serverLog("HEALTH-OK", { url: this.envoyUrl, responseTimeMs });
+        return { reachable: true, responseTimeMs, error: null };
+      }
+      serverWarn("HEALTH-FAILED", { url: this.envoyUrl, status: res.status, responseTimeMs });
+      return { reachable: false, responseTimeMs, error: `HTTP ${res.status}` };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      serverError("HEALTH-ERROR", { url: this.envoyUrl, error: message });
+      return {
+        reachable: false,
+        responseTimeMs: null,
+        error: message,
+      };
+    }
+  }
+}

package/src/agent/mcp-client-manager.ts

@@ -0,0 +1,131 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { McpServerConfig } from "@synth-deploy/core";
+
+export interface McpToolResult {
+  serverName: string;
+  toolName: string;
+  result: unknown;
+  error?: string;
+}
+
+/**
+ * Manages connections to external MCP servers (monitoring, incident management,
+ * etc.) and exposes their tools/resources for pre-deployment checks and
+ * diagnostic investigations.
+ *
+ * Design principles:
+ * - Graceful degradation: unreachable servers are logged and skipped, never block deployments
+ * - All external data access must be recorded to the Debrief by the caller
+ * - Lightweight: if no servers are configured, the manager is a no-op
+ */
+export class McpClientManager {
+  private clients: Map<string, { client: Client; config: McpServerConfig }> =
+    new Map();
+
+  async connect(config: McpServerConfig): Promise<void> {
+    try {
+      const transport = new StreamableHTTPClientTransport(new URL(config.url));
+      const client = new Client({
+        name: "synth-server",
+        version: "0.1.0",
+      });
+      await client.connect(transport);
+      this.clients.set(config.name, { client, config });
+    } catch (error) {
+      // Graceful degradation -- log but don't throw
+      console.warn(
+        `[MCP] Failed to connect to ${config.name} at ${config.url}: ${error}`,
+      );
+    }
+  }
+
+  async connectAll(configs: McpServerConfig[]): Promise<void> {
+    await Promise.allSettled(configs.map((c) => this.connect(c)));
+  }
+
+  async listTools(): Promise<
+    Array<{ server: string; name: string; description?: string }>
+  > {
+    const tools: Array<{
+      server: string;
+      name: string;
+      description?: string;
+    }> = [];
+    for (const [name, { client }] of this.clients) {
+      try {
+        const result = await client.listTools();
+        for (const tool of result.tools) {
+          tools.push({
+            server: name,
+            name: tool.name,
+            description: tool.description,
+          });
+        }
+      } catch {
+        // Server unreachable -- skip
+      }
+    }
+    return tools;
+  }
+
+  async callTool(
+    serverName: string,
+    toolName: string,
+    args: Record<string, unknown>,
+  ): Promise<McpToolResult> {
+    const entry = this.clients.get(serverName);
+    if (!entry) {
+      return {
+        serverName,
+        toolName,
+        result: null,
+        error: `Server '${serverName}' not connected`,
+      };
+    }
+    try {
+      const result = await entry.client.callTool({
+        name: toolName,
+        arguments: args,
+      });
+      return { serverName, toolName, result: result.content };
+    } catch (error) {
+      return { serverName, toolName, result: null, error: String(error) };
+    }
+  }
+
+  async listResources(
+    serverName: string,
+  ): Promise<Array<{ uri: string; name?: string }>> {
+    const entry = this.clients.get(serverName);
+    if (!entry) return [];
+    try {
+      const result = await entry.client.listResources();
+      return result.resources.map((r) => ({ uri: r.uri, name: r.name }));
+    } catch {
+      return [];
+    }
+  }
+
+  getConnectedServers(): string[] {
+    return Array.from(this.clients.keys());
+  }
+
+  async disconnect(serverName: string): Promise<void> {
+    const entry = this.clients.get(serverName);
+    if (entry) {
+      try {
+        await entry.client.close();
+      } catch {
+        /* ignore */
+      }
+      this.clients.delete(serverName);
+    }
+  }
+
+  async disconnectAll(): Promise<void> {
+    for (const name of this.clients.keys()) {
+      await this.disconnect(name);
+    }
+  }
+}

package/src/agent/stale-deployment-detector.ts

@@ -0,0 +1,79 @@
+import type { DebriefWriter } from "@synth-deploy/core";
+import type { DeploymentStore } from "./synth-agent.js";
+
+const DEFAULT_STALE_THRESHOLD_MS = Number(
+  process.env.SYNTH_STALE_DEPLOYMENT_TIMEOUT_MS ?? 30 * 60 * 1000, // 30 minutes
+);
+
+const DEFAULT_SCAN_INTERVAL_MS = Number(
+  process.env.SYNTH_STALE_SCAN_INTERVAL_MS ?? 60 * 1000, // 1 minute
+);
+
+/**
+ * Scans for deployments stuck in "running" status beyond the stale threshold
+ * and marks them as failed with a clear explanation.
+ *
+ * Returns the number of deployments marked as stale.
+ */
+export function markStaleDeployments(
+  deployments: DeploymentStore,
+  debrief: DebriefWriter,
+  thresholdMs: number = DEFAULT_STALE_THRESHOLD_MS,
+): number {
+  const now = Date.now();
+  const stale = deployments.list().filter(
+    (d) =>
+      d.status === "running" &&
+      now - new Date(d.createdAt).getTime() > thresholdMs,
+  );
+
+  for (const deployment of stale) {
+    deployment.status = "failed";
+    deployments.save(deployment);
+
+    const staleDurationMin = Math.round(
+      (now - new Date(deployment.createdAt).getTime()) / 60_000,
+    );
+
+    debrief.record({
+      partitionId: deployment.partitionId ?? null,
+      deploymentId: deployment.id,
+      agent: "server",
+      decisionType: "deployment-failure",
+      decision: `Marked deployment as failed: exceeded ${Math.round(thresholdMs / 60_000)} minute stale threshold`,
+      reasoning:
+        `Deployment ${deployment.id.slice(0, 8)} has been in "running" status for ${staleDurationMin} minutes ` +
+        `without receiving a completion report. This typically indicates Command lost connection to the Envoy ` +
+        `or the Envoy process crashed during execution. The deployment has been marked as failed to prevent ` +
+        `indefinite "running" status.`,
+      context: {
+        deploymentId: deployment.id,
+        partitionId: deployment.partitionId ?? null,
+        staleDurationMinutes: staleDurationMin,
+        thresholdMinutes: Math.round(thresholdMs / 60_000),
+      },
+    });
+  }
+
+  return stale.length;
+}
+
+/**
+ * Starts a periodic scan for stale deployments.
+ * Returns a cleanup function to stop the interval.
+ */
+export function startStaleDeploymentScanner(
+  deployments: DeploymentStore,
+  debrief: DebriefWriter,
+  intervalMs: number = DEFAULT_SCAN_INTERVAL_MS,
+  thresholdMs: number = DEFAULT_STALE_THRESHOLD_MS,
+): () => void {
+  const timer = setInterval(() => {
+    const count = markStaleDeployments(deployments, debrief, thresholdMs);
+    if (count > 0) {
+      console.log(`[stale-detector] Marked ${count} stale deployment(s) as failed`);
+    }
+  }, intervalMs);
+
+  return () => clearInterval(timer);
+}