@agents-txt/core 0.1.0

package/dist/index.js

@@ -0,0 +1,668 @@
+// src/utils.ts
+function sanitizeValue(value, maxLength = 500) {
+  const str = typeof value === "string" ? value : String(value ?? "");
+  return str.replace(/[\r\n]/g, " ").replace(/[\x00-\x1f]/g, "").trim().slice(0, maxLength);
+}
+function parseRateLimit(value) {
+  const match = value.match(/^(\d+)\/(second|minute|hour|day)$/);
+  if (!match) return null;
+  return { requests: parseInt(match[1], 10), window: match[2] };
+}
+function formatRateLimit(requests, window) {
+  return `${requests}/${window}`;
+}
+
+// src/parser.ts
+var VALID_PROTOCOLS = /* @__PURE__ */ new Set(["REST", "MCP", "A2A", "GraphQL", "WebSocket"]);
+var VALID_AUTH_TYPES = /* @__PURE__ */ new Set(["none", "api-key", "bearer-token", "oauth2", "hmac"]);
+var VALID_DECLARATION_TYPES = /* @__PURE__ */ new Set(["platform", "agent"]);
+function parse(input) {
+  const errors = [];
+  const warnings = [];
+  const lines = input.split(/\r?\n/);
+  let specVersion = "1.0";
+  let generatedAt;
+  let declarationType;
+  const operatesOn = [];
+  const site = {};
+  const capabilities = [];
+  const allowPaths = [];
+  const disallowPaths = [];
+  const agents = {};
+  const metadata = {};
+  let state = "TOP_LEVEL";
+  let currentCapability = null;
+  let currentAgentName = null;
+  let currentAgentPolicy = null;
+  function flushCapability() {
+    if (currentCapability && currentCapability.id) {
+      capabilities.push({
+        id: currentCapability.id,
+        description: currentCapability.description ?? "",
+        endpoint: currentCapability.endpoint ?? "",
+        method: currentCapability.method,
+        protocol: currentCapability.protocol ?? "REST",
+        auth: currentCapability.auth,
+        rateLimit: currentCapability.rateLimit,
+        openapi: currentCapability.openapi,
+        parameters: currentCapability.parameters,
+        scopes: currentCapability.scopes
+      });
+    }
+    currentCapability = null;
+  }
+  function flushAgent() {
+    if (currentAgentName !== null && currentAgentPolicy !== null) {
+      agents[currentAgentName] = currentAgentPolicy;
+    }
+    currentAgentName = null;
+    currentAgentPolicy = null;
+  }
+  for (let i = 0; i < lines.length; i++) {
+    const lineNum = i + 1;
+    const raw = lines[i];
+    const trimmed = raw.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) {
+      const specMatch = trimmed.match(/^#\s*Spec-Version:\s*(.+)/i);
+      if (specMatch) specVersion = specMatch[1].trim();
+      const genMatch = trimmed.match(/^#\s*Generated:\s*(.+)/i);
+      if (genMatch) generatedAt = genMatch[1].trim();
+      continue;
+    }
+    const isIndented = raw.startsWith("  ") || raw.startsWith("	");
+    if (isIndented && state === "IN_CAPABILITY" && currentCapability) {
+      const colonIdx2 = trimmed.indexOf(":");
+      if (colonIdx2 === -1) {
+        warnings.push({ line: lineNum, message: `Unparseable indented line: "${trimmed}"` });
+        continue;
+      }
+      const key2 = trimmed.slice(0, colonIdx2).trim();
+      const value2 = trimmed.slice(colonIdx2 + 1).trim();
+      switch (key2) {
+        case "Endpoint":
+          currentCapability.endpoint = value2;
+          break;
+        case "Method":
+          currentCapability.method = value2.toUpperCase();
+          break;
+        case "Protocol":
+          if (VALID_PROTOCOLS.has(value2)) {
+            currentCapability.protocol = value2;
+          } else {
+            warnings.push({ line: lineNum, field: "Protocol", message: `Unknown protocol: ${value2}` });
+            currentCapability.protocol = value2;
+          }
+          break;
+        case "Auth":
+          if (!currentCapability.auth) currentCapability.auth = { type: "none" };
+          if (VALID_AUTH_TYPES.has(value2)) {
+            currentCapability.auth.type = value2;
+          } else {
+            warnings.push({ line: lineNum, field: "Auth", message: `Unknown auth type: ${value2}` });
+          }
+          break;
+        case "Auth-Endpoint":
+          if (!currentCapability.auth) currentCapability.auth = { type: "bearer-token" };
+          currentCapability.auth.tokenEndpoint = value2;
+          break;
+        case "Auth-Docs":
+          if (!currentCapability.auth) currentCapability.auth = { type: "none" };
+          currentCapability.auth.docsUrl = value2;
+          break;
+        case "Scopes":
+          if (!currentCapability.auth) currentCapability.auth = { type: "oauth2" };
+          currentCapability.auth.scopes = value2.split(",").map((s) => s.trim());
+          break;
+        case "Rate-Limit": {
+          const rl = parseRateLimit(value2);
+          if (rl) {
+            currentCapability.rateLimit = { requests: rl.requests, window: rl.window };
+          } else {
+            warnings.push({ line: lineNum, field: "Rate-Limit", message: `Invalid rate limit: ${value2}` });
+          }
+          break;
+        }
+        case "Description":
+          currentCapability.description = value2;
+          break;
+        case "OpenAPI":
+          currentCapability.openapi = value2;
+          break;
+        case "Param": {
+          const parsed = parseParam(value2);
+          if (parsed) {
+            if (!currentCapability.parameters) currentCapability.parameters = [];
+            currentCapability.parameters.push(parsed);
+          } else {
+            warnings.push({ line: lineNum, field: "Param", message: `Invalid parameter: ${value2}` });
+          }
+          break;
+        }
+        default:
+          warnings.push({ line: lineNum, message: `Unknown capability field: ${key2}` });
+      }
+      continue;
+    }
+    if (isIndented && state === "IN_AGENT" && currentAgentPolicy) {
+      const colonIdx2 = trimmed.indexOf(":");
+      if (colonIdx2 === -1) continue;
+      const key2 = trimmed.slice(0, colonIdx2).trim();
+      const value2 = trimmed.slice(colonIdx2 + 1).trim();
+      switch (key2) {
+        case "Rate-Limit": {
+          const rl = parseRateLimit(value2);
+          if (rl) {
+            currentAgentPolicy.rateLimit = { requests: rl.requests, window: rl.window };
+          }
+          break;
+        }
+        case "Capabilities":
+          currentAgentPolicy.capabilities = value2.split(",").map((s) => s.trim());
+          break;
+        case "Agent-Declaration":
+          currentAgentPolicy.agentDeclaration = value2;
+          break;
+        default:
+          warnings.push({ line: lineNum, message: `Unknown agent field: ${key2}` });
+      }
+      continue;
+    }
+    if (state === "IN_CAPABILITY") {
+      flushCapability();
+      state = "TOP_LEVEL";
+    }
+    if (state === "IN_AGENT") {
+      flushAgent();
+      state = "TOP_LEVEL";
+    }
+    const colonIdx = trimmed.indexOf(":");
+    if (colonIdx === -1) {
+      warnings.push({ line: lineNum, message: `Unparseable line: "${trimmed}"` });
+      continue;
+    }
+    const key = trimmed.slice(0, colonIdx).trim();
+    const value = trimmed.slice(colonIdx + 1).trim();
+    switch (key) {
+      case "Site-Name":
+        site.name = value;
+        break;
+      case "Site-URL":
+        site.url = value;
+        break;
+      case "Description":
+      case "Site-Description":
+        site.description = value;
+        break;
+      case "Contact":
+      case "Site-Contact":
+        site.contact = value;
+        break;
+      case "Privacy-Policy":
+      case "Site-Privacy-Policy":
+        site.privacyPolicy = value;
+        break;
+      case "Declaration-Type":
+        if (VALID_DECLARATION_TYPES.has(value)) {
+          declarationType = value;
+        } else {
+          warnings.push({ line: lineNum, field: "Declaration-Type", message: `Unknown declaration type: ${value}` });
+        }
+        break;
+      case "Operates-On":
+        operatesOn.push(value);
+        break;
+      case "Allow":
+        allowPaths.push(value);
+        break;
+      case "Disallow":
+        disallowPaths.push(value);
+        break;
+      case "Agents-JSON":
+        metadata["Agents-JSON"] = value;
+        break;
+      case "Capability":
+        currentCapability = { id: value };
+        state = "IN_CAPABILITY";
+        break;
+      case "Agent":
+        currentAgentName = value;
+        currentAgentPolicy = {};
+        state = "IN_AGENT";
+        break;
+      default:
+        metadata[key] = value;
+    }
+  }
+  if (state === "IN_CAPABILITY") flushCapability();
+  if (state === "IN_AGENT") flushAgent();
+  if (!site.name) errors.push({ field: "Site-Name", message: "Site-Name is required" });
+  if (!site.url) errors.push({ field: "Site-URL", message: "Site-URL is required" });
+  if (errors.length > 0) {
+    return { success: false, errors, warnings };
+  }
+  const document = {
+    specVersion,
+    generatedAt,
+    declarationType,
+    operatesOn: operatesOn.length > 0 ? operatesOn : void 0,
+    site: {
+      name: site.name,
+      url: site.url,
+      description: site.description,
+      contact: site.contact,
+      privacyPolicy: site.privacyPolicy
+    },
+    capabilities,
+    access: {
+      allow: allowPaths.length > 0 ? allowPaths : ["*"],
+      disallow: disallowPaths
+    },
+    agents: Object.keys(agents).length > 0 ? agents : { "*": {} },
+    metadata: Object.keys(metadata).length > 0 ? metadata : void 0
+  };
+  return { success: true, document, errors, warnings };
+}
+function parseParam(value) {
+  const match = value.match(
+    /^(\w+)\s*\(\s*(\w+)\s*,\s*(\w+)(?:\s*,\s*(required))?\s*\)(?:\s*—\s*(.+))?$/
+  );
+  if (!match) return null;
+  const [, name, location, type, req, description] = match;
+  const validLocations = /* @__PURE__ */ new Set(["query", "path", "header", "body"]);
+  if (!validLocations.has(location)) return null;
+  return {
+    name,
+    in: location,
+    type,
+    required: req === "required",
+    description: description?.trim()
+  };
+}
+
+// src/schema.ts
+import { z } from "zod";
+var RateLimitWindowSchema = z.enum(["second", "minute", "hour", "day"]);
+var RateLimitSchema = z.object({
+  requests: z.number().int().positive(),
+  window: RateLimitWindowSchema
+});
+var AuthTypeSchema = z.enum(["none", "api-key", "bearer-token", "oauth2", "hmac"]);
+var AuthConfigSchema = z.object({
+  type: AuthTypeSchema,
+  tokenEndpoint: z.string().url().optional(),
+  docsUrl: z.string().url().optional(),
+  scopes: z.array(z.string()).optional()
+});
+var ProtocolSchema = z.enum(["REST", "MCP", "A2A", "GraphQL", "WebSocket"]);
+var ParameterDefSchema = z.object({
+  name: z.string().min(1),
+  in: z.enum(["query", "path", "header", "body"]),
+  type: z.string().min(1),
+  required: z.boolean().optional(),
+  default: z.unknown().optional(),
+  description: z.string().optional(),
+  max: z.number().optional(),
+  min: z.number().optional()
+});
+var CapabilitySchema = z.object({
+  id: z.string().min(1).max(100).regex(/^[a-z0-9][a-z0-9-]*$/, "Must be lowercase alphanumeric with hyphens"),
+  description: z.string().min(1).max(500),
+  endpoint: z.string().url(),
+  method: z.string().optional(),
+  protocol: ProtocolSchema,
+  auth: AuthConfigSchema.optional(),
+  rateLimit: RateLimitSchema.optional(),
+  openapi: z.string().url().optional(),
+  parameters: z.array(ParameterDefSchema).optional(),
+  scopes: z.array(z.string()).optional()
+});
+var SiteInfoSchema = z.object({
+  name: z.string().min(1).max(200),
+  url: z.string().url(),
+  description: z.string().max(500).optional(),
+  contact: z.string().email().optional(),
+  privacyPolicy: z.string().url().optional()
+});
+var AccessControlSchema = z.object({
+  allow: z.array(z.string()),
+  disallow: z.array(z.string())
+});
+var AgentPolicySchema = z.object({
+  rateLimit: RateLimitSchema.optional(),
+  capabilities: z.array(z.string()).optional(),
+  agentDeclaration: z.string().url().optional()
+});
+var DeclarationTypeSchema = z.enum(["platform", "agent"]);
+var AgentsTxtDocumentSchema = z.object({
+  specVersion: z.string().regex(/^\d+\.\d+$/, "Must be major.minor format"),
+  generatedAt: z.string().datetime().optional(),
+  declarationType: DeclarationTypeSchema.optional(),
+  operatesOn: z.array(z.string().url()).optional(),
+  site: SiteInfoSchema,
+  capabilities: z.array(CapabilitySchema),
+  access: AccessControlSchema,
+  agents: z.record(z.string(), AgentPolicySchema),
+  metadata: z.record(z.string(), z.string()).optional()
+});
+
+// src/parser-json.ts
+function parseJSON(input) {
+  let raw;
+  try {
+    raw = JSON.parse(input);
+  } catch (err) {
+    return {
+      success: false,
+      errors: [{ message: `Invalid JSON: ${err instanceof Error ? err.message : "parse error"}` }],
+      warnings: []
+    };
+  }
+  const result = AgentsTxtDocumentSchema.safeParse(raw);
+  if (!result.success) {
+    return {
+      success: false,
+      errors: result.error.issues.map((issue) => ({
+        field: issue.path.join("."),
+        message: issue.message
+      })),
+      warnings: []
+    };
+  }
+  return {
+    success: true,
+    document: result.data,
+    errors: [],
+    warnings: []
+  };
+}
+
+// src/generator.ts
+function generate(doc) {
+  const lines = [];
+  lines.push("# agents.txt \u2014 AI Agent Capability Declaration");
+  lines.push(`# Spec-Version: ${doc.specVersion}`);
+  if (doc.generatedAt) {
+    lines.push(`# Generated: ${doc.generatedAt}`);
+  }
+  lines.push("");
+  if (doc.declarationType) {
+    lines.push(`Declaration-Type: ${doc.declarationType}`);
+  }
+  if (doc.operatesOn) {
+    for (const url of doc.operatesOn) {
+      lines.push(`Operates-On: ${url}`);
+    }
+  }
+  if (doc.declarationType || doc.operatesOn) {
+    lines.push("");
+  }
+  lines.push(`Site-Name: ${sanitizeValue(doc.site.name)}`);
+  lines.push(`Site-URL: ${sanitizeValue(doc.site.url)}`);
+  if (doc.site.description) {
+    lines.push(`Description: ${sanitizeValue(doc.site.description)}`);
+  }
+  if (doc.site.contact) {
+    lines.push(`Contact: ${sanitizeValue(doc.site.contact)}`);
+  }
+  if (doc.site.privacyPolicy) {
+    lines.push(`Privacy-Policy: ${sanitizeValue(doc.site.privacyPolicy)}`);
+  }
+  lines.push("");
+  for (const cap of doc.capabilities) {
+    lines.push(`Capability: ${cap.id}`);
+    lines.push(`  Endpoint: ${cap.endpoint}`);
+    if (cap.method) {
+      lines.push(`  Method: ${cap.method}`);
+    }
+    lines.push(`  Protocol: ${cap.protocol}`);
+    if (cap.auth) {
+      lines.push(`  Auth: ${cap.auth.type}`);
+      if (cap.auth.tokenEndpoint) {
+        lines.push(`  Auth-Endpoint: ${cap.auth.tokenEndpoint}`);
+      }
+      if (cap.auth.docsUrl) {
+        lines.push(`  Auth-Docs: ${cap.auth.docsUrl}`);
+      }
+      if (cap.auth.scopes && cap.auth.scopes.length > 0) {
+        lines.push(`  Scopes: ${cap.auth.scopes.join(", ")}`);
+      }
+    }
+    if (cap.rateLimit) {
+      lines.push(`  Rate-Limit: ${formatRateLimit(cap.rateLimit.requests, cap.rateLimit.window)}`);
+    }
+    if (cap.description) {
+      lines.push(`  Description: ${sanitizeValue(cap.description)}`);
+    }
+    if (cap.openapi) {
+      lines.push(`  OpenAPI: ${cap.openapi}`);
+    }
+    if (cap.parameters) {
+      for (const param of cap.parameters) {
+        const parts = [param.in, param.type];
+        if (param.required) parts.push("required");
+        let line = `  Param: ${param.name} (${parts.join(", ")})`;
+        if (param.description) line += ` \u2014 ${sanitizeValue(param.description)}`;
+        lines.push(line);
+      }
+    }
+    lines.push("");
+  }
+  for (const pattern of doc.access.allow) {
+    lines.push(`Allow: ${pattern}`);
+  }
+  for (const pattern of doc.access.disallow) {
+    lines.push(`Disallow: ${pattern}`);
+  }
+  lines.push("");
+  for (const [agent, policy] of Object.entries(doc.agents)) {
+    lines.push(`Agent: ${agent}`);
+    if (policy.rateLimit) {
+      lines.push(`  Rate-Limit: ${formatRateLimit(policy.rateLimit.requests, policy.rateLimit.window)}`);
+    }
+    if (policy.capabilities && policy.capabilities.length > 0) {
+      lines.push(`  Capabilities: ${policy.capabilities.join(", ")}`);
+    }
+    if (policy.agentDeclaration) {
+      lines.push(`  Agent-Declaration: ${policy.agentDeclaration}`);
+    }
+  }
+  lines.push("");
+  if (doc.metadata) {
+    for (const [key, value] of Object.entries(doc.metadata)) {
+      lines.push(`${key}: ${sanitizeValue(value)}`);
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+
+// src/generator-json.ts
+function generateJSON(doc) {
+  return JSON.stringify(doc, null, 2);
+}
+
+// src/validator.ts
+function validate(doc) {
+  const errors = [];
+  const warnings = [];
+  const schemaResult = AgentsTxtDocumentSchema.safeParse(doc);
+  if (!schemaResult.success) {
+    for (const issue of schemaResult.error.issues) {
+      errors.push({
+        path: issue.path.join("."),
+        message: issue.message,
+        code: "SCHEMA_VIOLATION"
+      });
+    }
+  }
+  const capIds = /* @__PURE__ */ new Set();
+  for (const cap of doc.capabilities) {
+    if (capIds.has(cap.id)) {
+      errors.push({
+        path: `capabilities.${cap.id}`,
+        message: `Duplicate capability ID: "${cap.id}"`,
+        code: "DUPLICATE_CAPABILITY"
+      });
+    }
+    capIds.add(cap.id);
+  }
+  for (const [agentName, policy] of Object.entries(doc.agents)) {
+    if (policy.capabilities) {
+      for (const capId of policy.capabilities) {
+        if (!capIds.has(capId)) {
+          errors.push({
+            path: `agents.${agentName}.capabilities`,
+            message: `Agent "${agentName}" references unknown capability: "${capId}"`,
+            code: "UNKNOWN_CAPABILITY_REF"
+          });
+        }
+      }
+    }
+  }
+  if (doc.declarationType === "agent" && (!doc.operatesOn || doc.operatesOn.length === 0)) {
+    warnings.push({
+      path: "operatesOn",
+      message: "Agent declarations should include at least one Operates-On URL",
+      code: "MISSING_OPERATES_ON"
+    });
+  }
+  if (doc.operatesOn && doc.operatesOn.length > 0 && doc.declarationType !== "agent") {
+    warnings.push({
+      path: "declarationType",
+      message: 'Operates-On is set but Declaration-Type is not "agent"',
+      code: "OPERATES_ON_WITHOUT_AGENT_TYPE"
+    });
+  }
+  if (doc.site.url && !doc.site.url.startsWith("https://")) {
+    warnings.push({
+      path: "site.url",
+      message: "Site URL should use HTTPS",
+      code: "INSECURE_URL"
+    });
+  }
+  for (const cap of doc.capabilities) {
+    if (cap.endpoint && !cap.endpoint.startsWith("https://")) {
+      warnings.push({
+        path: `capabilities.${cap.id}.endpoint`,
+        message: `Capability "${cap.id}" endpoint should use HTTPS`,
+        code: "INSECURE_ENDPOINT"
+      });
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function validateText(text) {
+  const parseResult = parse(text);
+  if (!parseResult.success || !parseResult.document) {
+    return {
+      valid: false,
+      errors: parseResult.errors.map((e) => ({
+        path: e.field ?? "",
+        message: e.message,
+        code: "PARSE_ERROR"
+      })),
+      warnings: []
+    };
+  }
+  return validate(parseResult.document);
+}
+function validateJSON(json) {
+  const parseResult = parseJSON(json);
+  if (!parseResult.success || !parseResult.document) {
+    return {
+      valid: false,
+      errors: parseResult.errors.map((e) => ({
+        path: e.field ?? "",
+        message: e.message,
+        code: "PARSE_ERROR"
+      })),
+      warnings: []
+    };
+  }
+  return validate(parseResult.document);
+}
+
+// src/client.ts
+var WELL_KNOWN_TXT = "/.well-known/agents.txt";
+var FALLBACK_TXT = "/agents.txt";
+var WELL_KNOWN_JSON = "/.well-known/agents.json";
+var FALLBACK_JSON = "/agents.json";
+var AgentsTxtClient = class {
+  timeout;
+  userAgent;
+  constructor(options = {}) {
+    this.timeout = options.timeout ?? 1e4;
+    this.userAgent = options.userAgent ?? "agents-txt-client/0.1";
+  }
+  /**
+   * Discover agents.txt from a site. Tries /.well-known/agents.txt first,
+   * falls back to /agents.txt.
+   */
+  async discover(baseUrl) {
+    const normalized = baseUrl.replace(/\/+$/, "");
+    const primary = await this.fetchText(`${normalized}${WELL_KNOWN_TXT}`);
+    if (primary) return parse(primary);
+    const fallback = await this.fetchText(`${normalized}${FALLBACK_TXT}`);
+    if (fallback) return parse(fallback);
+    return {
+      success: false,
+      errors: [{ message: `No agents.txt found at ${normalized}` }],
+      warnings: []
+    };
+  }
+  /**
+   * Discover agents.json from a site. Tries /.well-known/agents.json first,
+   * falls back to /agents.json.
+   */
+  async discoverJSON(baseUrl) {
+    const normalized = baseUrl.replace(/\/+$/, "");
+    const primary = await this.fetchText(`${normalized}${WELL_KNOWN_JSON}`);
+    if (primary) return parseJSON(primary);
+    const fallback = await this.fetchText(`${normalized}${FALLBACK_JSON}`);
+    if (fallback) return parseJSON(fallback);
+    return {
+      success: false,
+      errors: [{ message: `No agents.json found at ${normalized}` }],
+      warnings: []
+    };
+  }
+  async fetchText(url) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        headers: { "User-Agent": this.userAgent },
+        signal: controller.signal
+      });
+      if (!response.ok) return null;
+      return await response.text();
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+export {
+  AgentsTxtClient,
+  AgentsTxtDocumentSchema,
+  AuthConfigSchema,
+  CapabilitySchema,
+  DeclarationTypeSchema,
+  ProtocolSchema,
+  RateLimitSchema,
+  SiteInfoSchema,
+  formatRateLimit,
+  generate,
+  generateJSON,
+  parse,
+  parseJSON,
+  parseRateLimit,
+  sanitizeValue,
+  validate,
+  validateJSON,
+  validateText
+};