agent-relay-server 0.4.39 → 0.6.0

package/src/connectors.ts

@@ -0,0 +1,256 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { ConnectorAction, ConnectorActionResult, ConnectorManifest, ConnectorSummary } from "./types";
+import { ValidationError } from "./db";
+
+const CONNECTOR_SCHEMA = "agent-relay.connector.v1";
+const VALID_KINDS = new Set(["channel", "event", "provider", "orchestrator"]);
+const VALID_ACTIONS = new Set(["install", "uninstall", "enable", "disable", "start", "stop", "restart", "status", "doctor"]);
+
+function connectorRegistryDir(): string {
+  const configured = process.env.AGENT_RELAY_CONNECTORS_DIR;
+  if (configured) return resolveHome(configured);
+  return join(homedir(), ".agent-relay", "connectors");
+}
+
+function resolveHome(path: string): string {
+  return path.startsWith("~") ? join(homedir(), path.slice(1)) : path;
+}
+
+function connectorDir(id: string): string {
+  validateConnectorId(id);
+  return join(connectorRegistryDir(), id);
+}
+
+function readJsonFile(path: string): unknown {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function readRecordFile(path: string): Record<string, unknown> | undefined {
+  if (!existsSync(path)) return undefined;
+  const parsed = readJsonFile(path);
+  return isRecord(parsed) ? parsed : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function validateConnectorId(id: string): void {
+  if (!/^[a-z0-9][a-z0-9._-]{0,79}$/.test(id)) {
+    throw new ValidationError("connector id must be lowercase alphanumeric plus dot, underscore, or dash");
+  }
+}
+
+function normalizeConnectorManifest(value: unknown): ConnectorManifest {
+  if (!isRecord(value)) throw new ValidationError("connector manifest must be an object");
+  if (value.schema !== CONNECTOR_SCHEMA) throw new ValidationError(`connector manifest schema must be ${CONNECTOR_SCHEMA}`);
+  const id = stringField(value, "id");
+  validateConnectorId(id);
+  const kind = stringField(value, "kind");
+  if (!VALID_KINDS.has(kind)) throw new ValidationError("connector kind must be channel, event, provider, or orchestrator");
+  const binary = stringField(value, "binary");
+  const displayName = stringField(value, "displayName");
+  const version = stringField(value, "version");
+  const commands = value.commands;
+  if (!isRecord(commands)) throw new ValidationError("connector commands must be an object");
+
+  const normalizedCommands: ConnectorManifest["commands"] = {};
+  for (const [action, command] of Object.entries(commands)) {
+    if (!VALID_ACTIONS.has(action)) throw new ValidationError(`unsupported connector action: ${action}`);
+    if (!Array.isArray(command) || !command.every((part) => typeof part === "string" && part.trim())) {
+      throw new ValidationError(`connector command ${action} must be a non-empty string array`);
+    }
+    normalizedCommands[action as ConnectorAction] = command;
+  }
+
+  return {
+    schema: CONNECTOR_SCHEMA,
+    id,
+    kind: kind as ConnectorManifest["kind"],
+    packageName: optionalString(value.packageName),
+    binary,
+    displayName,
+    description: optionalString(value.description),
+    version,
+    capabilities: stringArray(value.capabilities, "capabilities"),
+    commands: normalizedCommands,
+    configSchema: isRecord(value.configSchema) ? value.configSchema : undefined,
+  };
+}
+
+function stringField(record: Record<string, unknown>, field: string): string {
+  const value = record[field];
+  if (typeof value !== "string" || !value.trim()) throw new ValidationError(`connector ${field} required`);
+  if (value.length > 500) throw new ValidationError(`connector ${field} is too long`);
+  return value;
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function stringArray(value: unknown, field: string): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+    throw new ValidationError(`connector ${field} must be an array of strings`);
+  }
+  return [...new Set(value.map((item) => item.trim()).filter(Boolean))];
+}
+
+export function registerConnectorManifest(manifest: ConnectorManifest, opts: { config?: Record<string, unknown>; state?: Record<string, unknown> } = {}): ConnectorSummary {
+  const normalized = normalizeConnectorManifest(manifest);
+  const dir = connectorDir(normalized.id);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  writeFileSync(join(dir, "manifest.json"), JSON.stringify(normalized, null, 2) + "\n", { mode: 0o600 });
+  if (opts.config) writeConnectorConfig(normalized.id, opts.config);
+  if (opts.state) writeFileSync(join(dir, "state.json"), JSON.stringify(opts.state, null, 2) + "\n", { mode: 0o600 });
+  return getConnector(normalized.id)!;
+}
+
+export function listConnectors(): ConnectorSummary[] {
+  const root = connectorRegistryDir();
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .flatMap((entry) => {
+      try {
+        const connector = getConnector(entry.name);
+        return connector ? [connector] : [];
+      } catch {
+        return [];
+      }
+    })
+    .sort((a, b) => a.displayName.localeCompare(b.displayName));
+}
+
+export function getConnector(id: string): ConnectorSummary | null {
+  const dir = connectorDir(id);
+  const manifestPath = join(dir, "manifest.json");
+  if (!existsSync(manifestPath)) return null;
+  const manifest = normalizeConnectorManifest(readJsonFile(manifestPath));
+  const config = readRecordFile(join(dir, "config.json"));
+  const state = readRecordFile(join(dir, "state.json"));
+  return {
+    id: manifest.id,
+    kind: manifest.kind,
+    displayName: manifest.displayName,
+    description: manifest.description,
+    version: manifest.version,
+    packageName: manifest.packageName,
+    binary: manifest.binary,
+    capabilities: manifest.capabilities,
+    registryPath: dir,
+    manifest,
+    config,
+    state,
+    runtime: summarizeRuntime(manifest, state),
+  };
+}
+
+function summarizeRuntime(manifest: ConnectorManifest, state?: Record<string, unknown>): ConnectorSummary["runtime"] {
+  return {
+    installed: true,
+    enabled: typeof state?.enabled === "boolean" ? state.enabled : undefined,
+    running: typeof state?.running === "boolean" ? state.running : undefined,
+    status: typeof state?.status === "string" && ["ok", "warn", "error", "unknown"].includes(state.status) ? state.status as any : "unknown",
+    detail: typeof state?.detail === "string" ? state.detail : undefined,
+    updatedAt: typeof state?.updatedAt === "string" ? state.updatedAt : undefined,
+    raw: state?.raw ?? (manifest.commands.status ? undefined : { detail: "status command not declared" }),
+  };
+}
+
+export function readConnectorConfig(id: string): Record<string, unknown> {
+  return readRecordFile(join(connectorDir(id), "config.json")) ?? {};
+}
+
+export function writeConnectorConfig(id: string, config: Record<string, unknown>): Record<string, unknown> {
+  if (!isRecord(config)) throw new ValidationError("connector config must be an object");
+  const path = join(connectorDir(id), "config.json");
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+  return config;
+}
+
+export function runConnectorAction(id: string, action: ConnectorAction): ConnectorActionResult {
+  if (!VALID_ACTIONS.has(action)) throw new ValidationError("unsupported connector action");
+  const connector = getConnector(id);
+  if (!connector) throw new ValidationError(`connector ${id} not found`);
+  const command = connector.manifest.commands[action];
+  if (!command?.length) throw new ValidationError(`connector ${id} does not support ${action}`);
+
+  const proc = Bun.spawnSync({
+    cmd: command,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env, AGENT_RELAY_CONNECTOR_ID: id, AGENT_RELAY_CONNECTORS_DIR: connectorRegistryDir() },
+  });
+  const stdout = new TextDecoder().decode(proc.stdout).trim();
+  const stderr = new TextDecoder().decode(proc.stderr).trim();
+  const parsed = parseJsonMaybe(stdout);
+  const ok = proc.success;
+  const result: ConnectorActionResult = {
+    connectorId: id,
+    action,
+    command,
+    ok,
+    exitCode: proc.exitCode,
+    stdout,
+    stderr,
+    parsed,
+  };
+  if ((action === "status" || action === "doctor") && ok) {
+    writeActionState(id, action, parsed ?? stdout);
+  }
+  return result;
+}
+
+function parseJsonMaybe(value: string): unknown {
+  if (!value) return undefined;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return undefined;
+  }
+}
+
+function writeActionState(id: string, action: ConnectorAction, raw: unknown): void {
+  const current = readRecordFile(join(connectorDir(id), "state.json")) ?? {};
+  const next = {
+    ...current,
+    status: action === "doctor" ? doctorStatus(raw) : statusValue(raw),
+    detail: detailValue(raw),
+    running: runningValue(raw),
+    enabled: enabledValue(raw),
+    updatedAt: new Date().toISOString(),
+    raw,
+  };
+  writeFileSync(join(connectorDir(id), "state.json"), JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+}
+
+function statusValue(raw: unknown): ConnectorSummary["runtime"]["status"] {
+  if (isRecord(raw) && typeof raw.status === "string" && ["ok", "warn", "error", "unknown"].includes(raw.status)) return raw.status as any;
+  return "unknown";
+}
+
+function doctorStatus(raw: unknown): ConnectorSummary["runtime"]["status"] {
+  if (!isRecord(raw) || !Array.isArray(raw.checks)) return statusValue(raw);
+  if (raw.checks.some((check) => isRecord(check) && check.status === "error")) return "error";
+  if (raw.checks.some((check) => isRecord(check) && check.status === "warn")) return "warn";
+  return "ok";
+}
+
+function detailValue(raw: unknown): string | undefined {
+  if (isRecord(raw) && typeof raw.detail === "string") return raw.detail;
+  if (isRecord(raw) && typeof raw.summary === "string") return raw.summary;
+  return undefined;
+}
+
+function runningValue(raw: unknown): boolean | undefined {
+  return isRecord(raw) && typeof raw.running === "boolean" ? raw.running : undefined;
+}
+
+function enabledValue(raw: unknown): boolean | undefined {
+  return isRecord(raw) && typeof raw.enabled === "boolean" ? raw.enabled : undefined;
+}