Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

8.8 KB
Raw Blame
import { readFile } from 'node:fs/promises';
import { arch, platform } from 'node:os';
import { join } from 'node:path';
import {
  ACP_AGENT_EDITOR_ID_MAP,
  ACP_FEATURED_AGENT_IDS,
  type EditorId,
} from '@inkeep/open-knowledge-core';
import type { PinoLogger } from '../logger.ts';

const ACP_REGISTRY_URL = 'https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json';

export const FEATURED_AGENT_IDS: readonly string[] = ACP_FEATURED_AGENT_IDS;

export const ACP_AGENT_EDITOR_IDS: { readonly [agentId: string]: EditorId | undefined } =
  ACP_AGENT_EDITOR_ID_MAP;

export interface RegistryBinaryTarget {
  archive: string;
  sha256?: string;
  cmd: string;
  args?: string[];
  env?: Record<string, string>;
}

interface RegistryPackageDistribution {
  package: string;
  args?: string[];
  env?: Record<string, string>;
}

interface RegistryDistribution {
  npx?: RegistryPackageDistribution;
  uvx?: RegistryPackageDistribution;
  binary?: Record<string, RegistryBinaryTarget>;
}

export interface RegistryAgent {
  id: string;
  name: string;
  version: string;
  description?: string;
  repository?: string;
  website?: string;
  authors?: string[];
  license?: string;
  icon?: string;
  distribution: RegistryDistribution;
}

export interface CustomAgentEntry {
  id: string;
  name: string;
  command: string;
  args?: string[];
  env?: Record<string, string>;
}

export interface CatalogResult {
  agents: RegistryAgent[];
  fetchedAt: number;
  stale: boolean;
}

const CUSTOM_AGENTS_FILE = 'acp-agents.json';
const REGISTRY_CACHE_FILE = 'acp-registry-cache.json';
const DEFAULT_TTL_MS = 60 * 60 * 1000;

export function registryPlatformKey(): string | null {
  const os = platform();
  const cpu = arch();
  const osKey =
    os === 'darwin' ? 'darwin' : os === 'linux' ? 'linux' : os === 'win32' ? 'windows' : null;
  const cpuKey = cpu === 'arm64' ? 'aarch64' : cpu === 'x64' ? 'x86_64' : null;
  if (osKey === null || cpuKey === null) return null;
  return `${osKey}-${cpuKey}`;
}

const LOWERCASE_BRAND_AGENT_IDS: ReadonlySet<string> = new Set(['goose', 'fast-agent', 'crow-cli']);

export function normalizeAgentDisplayName(id: string, name: string): string {
  const trimmed = name.trim();
  if (trimmed.length === 0) return id;
  if (LOWERCASE_BRAND_AGENT_IDS.has(id)) return trimmed;
  if (trimmed !== trimmed.toLowerCase()) return trimmed;
  return trimmed
    .split(/\s+/)
    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
    .join(' ');
}

function isRegistryAgent(value: unknown): value is RegistryAgent {
  if (typeof value !== 'object' || value === null) return false;
  const a = value as Record<string, unknown>;
  return (
    typeof a.id === 'string' &&
    a.id.length > 0 &&
    typeof a.name === 'string' &&
    typeof a.version === 'string' &&
    typeof a.distribution === 'object' &&
    a.distribution !== null
  );
}

function parseCatalogJson(text: string): RegistryAgent[] | null {
  let parsed: unknown;
  try {
    parsed = JSON.parse(text);
  } catch {
    return null;
  }
  const agents = (parsed as { agents?: unknown })?.agents;
  if (!Array.isArray(agents)) return null;
  return agents
    .filter(isRegistryAgent)
    .map((agent) => ({ ...agent, name: normalizeAgentDisplayName(agent.id, agent.name) }));
}

export class AcpRegistry {
  private readonly localDir: string;
  private readonly log: PinoLogger;
  private readonly ttlMs: number;
  private readonly fetchImpl: typeof fetch;
  private memory: CatalogResult | null = null;
  private inflight: Promise<CatalogResult> | null = null;

  constructor(opts: {
    localDir: string;
    log: PinoLogger;
    ttlMs?: number;
    fetchImpl?: typeof fetch;
  }) {
    this.localDir = opts.localDir;
    this.log = opts.log;
    this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
    this.fetchImpl = opts.fetchImpl ?? fetch;
  }

  async getCatalog(): Promise<CatalogResult> {
    if (
      this.memory !== null &&
      Date.now() - this.memory.fetchedAt < this.ttlMs &&
      !this.memory.stale
    ) {
      return this.memory;
    }
    if (this.inflight !== null) return this.inflight;
    this.inflight = this.refresh().finally(() => {
      this.inflight = null;
    });
    return this.inflight;
  }

  async getAgent(id: string): Promise<RegistryAgent | undefined> {
    const { agents } = await this.getCatalog();
    return agents.find((a) => a.id === id);
  }

  private async refresh(): Promise<CatalogResult> {
    try {
      const res = await this.fetchImpl(ACP_REGISTRY_URL, {
        signal: AbortSignal.timeout(15_000),
      });
      if (!res.ok) throw new Error(`registry fetch failed: HTTP ${res.status}`);
      const text = await res.text();
      const agents = parseCatalogJson(text);
      if (agents === null) throw new Error('registry payload did not parse as a catalog');
      this.memory = { agents, fetchedAt: Date.now(), stale: false };
      try {
        const { tracedMkdir, tracedWriteFile } = await import('../fs-traced.ts');
        await tracedMkdir(this.localDir, { recursive: true });
        await tracedWriteFile(join(this.localDir, REGISTRY_CACHE_FILE), text);
      } catch (err) {
        this.log.warn({ err }, '[acp-registry] disk cache write failed');
      }
      return this.memory;
    } catch (err) {
      const fallback = await this.readDiskCache();
      if (fallback !== null) {
        this.log.warn({ err }, '[acp-registry] CDN unreachable — serving disk cache');
        this.memory = fallback;
        return fallback;
      }
      if (this.memory !== null) {
        this.log.warn({ err }, '[acp-registry] CDN unreachable — serving stale memory copy');
        this.memory = { ...this.memory, stale: true };
        return this.memory;
      }
      throw err instanceof Error ? err : new Error(String(err));
    }
  }

  private async readDiskCache(): Promise<CatalogResult | null> {
    try {
      const text = await readFile(join(this.localDir, REGISTRY_CACHE_FILE), 'utf8');
      const agents = parseCatalogJson(text);
      if (agents === null) return null;
      return { agents, fetchedAt: 0, stale: true };
    } catch {
      return null;
    }
  }
}

export async function loadCustomAgents(
  localDir: string,
  log: PinoLogger,
): Promise<CustomAgentEntry[]> {
  let text: string;
  try {
    text = await readFile(join(localDir, CUSTOM_AGENTS_FILE), 'utf8');
  } catch {
    return [];
  }
  let parsed: unknown;
  try {
    parsed = JSON.parse(text);
  } catch (err) {
    log.warn(
      { error: err instanceof Error ? err.name : 'unknown', position: jsonErrorPosition(err) },
      `[acp-registry] ${CUSTOM_AGENTS_FILE} is not valid JSON — ignoring`,
    );
    return [];
  }
  if (!Array.isArray(parsed)) {
    log.warn(
      { topLevel: parsed === null ? 'null' : typeof parsed },
      `[acp-registry] ${CUSTOM_AGENTS_FILE} must be a JSON array of agents — ignoring`,
    );
    return [];
  }
  const valid: CustomAgentEntry[] = [];
  for (const [index, raw] of parsed.entries()) {
    const result = parseCustomAgentEntry(raw);
    if (result.ok) {
      valid.push(result.entry);
    } else {
      log.warn(
        { index, id: result.id, problem: result.problem },
        `[acp-registry] dropping malformed ${CUSTOM_AGENTS_FILE} entry`,
      );
    }
  }
  return valid;
}

function jsonErrorPosition(err: unknown): number | undefined {
  if (!(err instanceof Error)) return undefined;
  const match = /at position (\d+)/.exec(err.message);
  return match === null ? undefined : Number(match[1]);
}

type ParsedCustomAgentEntry =
  | { ok: true; entry: CustomAgentEntry }
  | { ok: false; id: string | undefined; problem: string };

function parseCustomAgentEntry(raw: unknown): ParsedCustomAgentEntry {
  const e = (typeof raw === 'object' && raw !== null && !Array.isArray(raw) ? raw : {}) as Record<
    string,
    unknown
  >;
  const id = typeof e.id === 'string' ? e.id : undefined;
  const reject = (problem: string): ParsedCustomAgentEntry => ({ ok: false, id, problem });
  if (id === undefined || !/^[a-zA-Z0-9_-]+$/.test(id)) {
    return reject('id must use only letters, digits, _ and -');
  }
  if (typeof e.name !== 'string') return reject('name must be a string');
  if (typeof e.command !== 'string' || e.command.length === 0) {
    return reject('command must be a non-empty string');
  }
  if (
    e.args !== undefined &&
    !(Array.isArray(e.args) && e.args.every((a) => typeof a === 'string'))
  ) {
    return reject('args must be an array of strings');
  }
  if (
    e.env !== undefined &&
    !(
      typeof e.env === 'object' &&
      e.env !== null &&
      !Array.isArray(e.env) &&
      Object.values(e.env).every((v) => typeof v === 'string')
    )
  ) {
    return reject('env must be an object of string values');
  }
  return {
    ok: true,
    entry: {
      id,
      name: e.name,
      command: e.command,
      args: e.args as string[] | undefined,
      env: (e.env as Record<string, string> | undefined) ?? undefined,
    },
  };
}