@cleocode/lafs-protocol 1.2.3 → 1.3.1

package/dist/src/discovery.d.ts

@@ -1,10 +1,111 @@
 /**
  * LAFS Agent Discovery - Express/Fastify Middleware
- * Serves discovery document at /.well-known/lafs.json
+ * Serves A2A-compliant Agent Card at /.well-known/agent-card.json
+ * Maintains backward compatibility with legacy /.well-known/lafs.json
+ *
+ * A2A v1.0+ Compliant Implementation
+ * Reference: specs/external/agent-discovery.md
  */
 import type { RequestHandler } from "express";
 /**
- * Capability definition for service advertisement
+ * A2A Agent Provider information
+ */
+export interface AgentProvider {
+    /** Organization URL */
+    url: string;
+    /** Organization name */
+    organization: string;
+}
+/**
+ * A2A Agent Capabilities
+ */
+export interface AgentCapabilities {
+    /** Supports streaming responses */
+    streaming?: boolean;
+    /** Supports push notifications */
+    pushNotifications?: boolean;
+    /** Supports extended agent card */
+    extendedAgentCard?: boolean;
+    /** Supported extensions */
+    extensions?: AgentExtension[];
+}
+/**
+ * A2A Agent Extension declaration
+ */
+export interface AgentExtension {
+    /** Extension URI (unique identifier) */
+    uri: string;
+    /** Human-readable description */
+    description: string;
+    /** Whether the extension is required */
+    required: boolean;
+    /** Extension-specific parameters */
+    params?: Record<string, unknown>;
+}
+/**
+ * A2A Agent Skill
+ */
+export interface AgentSkill {
+    /** Skill unique identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Detailed description */
+    description: string;
+    /** Keywords/tags for the skill */
+    tags: string[];
+    /** Example prompts */
+    examples?: string[];
+    /** Supported input modes (overrides agent defaults) */
+    inputModes?: string[];
+    /** Supported output modes (overrides agent defaults) */
+    outputModes?: string[];
+}
+/**
+ * Security scheme for authentication (OpenAPI 3.0 style)
+ */
+export interface SecurityScheme {
+    type: "http" | "apiKey" | "oauth2" | "openIdConnect";
+    description?: string;
+    scheme?: string;
+    bearerFormat?: string;
+}
+/**
+ * A2A v1.0 Agent Card - Standard format for agent discovery
+ * Reference: specs/external/specification.md Section 5
+ */
+export interface AgentCard {
+    /** JSON Schema URL */
+    $schema?: string;
+    /** Human-readable agent name */
+    name: string;
+    /** Detailed description of agent capabilities */
+    description: string;
+    /** Agent version (SemVer) */
+    version: string;
+    /** Base URL for A2A endpoints */
+    url: string;
+    /** Service provider information */
+    provider?: AgentProvider;
+    /** Agent capabilities */
+    capabilities: AgentCapabilities;
+    /** Supported input content types */
+    defaultInputModes: string[];
+    /** Supported output content types */
+    defaultOutputModes: string[];
+    /** Agent skills/capabilities */
+    skills: AgentSkill[];
+    /** Security authentication schemes */
+    securitySchemes?: Record<string, SecurityScheme>;
+    /** Required security schemes */
+    security?: Array<Record<string, string[]>>;
+    /** Documentation URL */
+    documentationUrl?: string;
+    /** Icon URL */
+    iconUrl?: string;
+}
+/**
+ * @deprecated Use AgentSkill instead
  */
 export interface Capability {
     name: string;
@@ -14,7 +115,7 @@ export interface Capability {
     optional?: boolean;
 }
 /**
- * Service configuration for discovery document
+ * @deprecated Use AgentCard instead
  */
 export interface ServiceConfig {
     name: string;
@@ -22,7 +123,7 @@ export interface ServiceConfig {
     description?: string;
 }
 /**
- * Endpoint configuration for discovery document
+ * @deprecated Will be removed in v2.0.0
  */
 export interface EndpointConfig {
     envelope: string;
@@ -30,7 +131,7 @@ export interface EndpointConfig {
     discovery: string;
 }
 /**
- * Complete discovery document served at /.well-known/lafs.json
+ * @deprecated Use AgentCard instead
  */
 export interface DiscoveryDocument {
     $schema: string;
@@ -40,82 +141,115 @@ export interface DiscoveryDocument {
     endpoints: EndpointConfig;
 }
 /**
- * Configuration for the discovery middleware
+ * Configuration for the discovery middleware (A2A v1.0 format)
  */
 export interface DiscoveryConfig {
-    /** Service information */
-    service: ServiceConfig;
-    /** List of capabilities this service provides */
-    capabilities: Capability[];
-    /** Endpoint URLs - can be relative paths or absolute URLs */
-    endpoints: {
-        /** URL for envelope submission endpoint */
-        envelope: string;
-        /** Optional URL for context ledger endpoint */
-        context?: string;
-        /** URL for this discovery document (usually auto-detected) */
-        discovery?: string;
-    };
+    /** Agent information (required for A2A v1.0; omit only with legacy 'service') */
+    agent?: Omit<AgentCard, '$schema'>;
+    /** Base URL for constructing absolute URLs */
+    baseUrl?: string;
     /** Cache duration in seconds (default: 3600) */
     cacheMaxAge?: number;
-    /** LAFS protocol version (default: "1.0.0") */
-    lafsVersion?: string;
     /** Schema URL override */
     schemaUrl?: string;
-    /** Base URL for constructing absolute URLs */
-    baseUrl?: string;
-    /** Optional custom headers to include in response */
+    /** Optional custom headers */
     headers?: Record<string, string>;
+    /**
+     * Automatically include LAFS as an A2A extension in Agent Card.
+     * Pass `true` for defaults, or an object to customize parameters.
+     */
+    autoIncludeLafsExtension?: boolean | {
+        required?: boolean;
+        supportsContextLedger?: boolean;
+        supportsTokenBudgets?: boolean;
+    };
+    /**
+     * @deprecated Use 'agent' instead
+     */
+    service?: ServiceConfig;
+    /**
+     * @deprecated Use 'agent.skills' instead
+     */
+    capabilities?: Capability[];
+    /**
+     * @deprecated Use 'agent.url' and individual endpoints
+     */
+    endpoints?: {
+        envelope: string;
+        context?: string;
+        discovery?: string;
+    };
+    /**
+     * @deprecated Use 'agent.version' instead
+     */
+    lafsVersion?: string;
 }
 /**
  * Discovery middleware options
  */
 export interface DiscoveryMiddlewareOptions {
-    /** Path to serve discovery document (default: /.well-known/lafs.json) */
+    /**
+     * Primary path to serve Agent Card (default: /.well-known/agent-card.json)
+     */
     path?: string;
+    /**
+     * Legacy path for backward compatibility (default: /.well-known/lafs.json)
+     * @deprecated Will be removed in v2.0.0
+     */
+    legacyPath?: string;
+    /** Enable legacy path support (default: true) */
+    enableLegacyPath?: boolean;
     /** Enable HEAD requests (default: true) */
     enableHead?: boolean;
     /** Enable ETag caching (default: true) */
     enableEtag?: boolean;
 }
 /**
- * Create Express middleware for serving LAFS discovery document
+ * Create Express middleware for serving A2A Agent Card
+ *
+ * Serves A2A-compliant Agent Card at /.well-known/agent-card.json
+ * Maintains backward compatibility with legacy /.well-known/lafs.json
  *
- * @param config - Discovery configuration
+ * @param config - Discovery configuration (A2A v1.0 format)
  * @param options - Middleware options
  * @returns Express RequestHandler
  *
  * @example
  * ```typescript
  * import express from "express";
- * import { discoveryMiddleware } from "./discovery.js";
+ * import { discoveryMiddleware } from "@cleocode/lafs-protocol/discovery";
  *
  * const app = express();
  *
  * app.use(discoveryMiddleware({
- *   service: {
- *     name: "my-lafs-service",
+ *   agent: {
+ *     name: "my-lafs-agent",
+ *     description: "A LAFS-compliant agent with A2A support",
  *     version: "1.0.0",
- *     description: "A LAFS-compliant API service"
- *   },
- *   capabilities: [
- *     {
- *       name: "envelope-processor",
- *       version: "1.0.0",
- *       operations: ["process", "validate"],
- *       description: "Process LAFS envelopes"
- *     }
- *   ],
- *   endpoints: {
- *     envelope: "/api/v1/envelope",
- *     context: "/api/v1/context"
+ *     url: "https://api.example.com",
+ *     capabilities: {
+ *       streaming: true,
+ *       pushNotifications: false,
+ *       extensions: []
+ *     },
+ *     defaultInputModes: ["application/json", "text/plain"],
+ *     defaultOutputModes: ["application/json"],
+ *     skills: [
+ *       {
+ *         id: "envelope-processor",
+ *         name: "Envelope Processor",
+ *         description: "Process LAFS envelopes",
+ *         tags: ["lafs", "envelope", "validation"],
+ *         examples: ["Validate this envelope", "Process envelope data"]
+ *       }
+ *     ]
  *   }
  * }));
  * ```
  */
 export declare function discoveryMiddleware(config: DiscoveryConfig, options?: DiscoveryMiddlewareOptions): RequestHandler;
 /**
- * Fastify plugin for LAFS discovery (for Fastify users)
+ * Fastify plugin for A2A Agent Card discovery
  *
  * @param fastify - Fastify instance
  * @param options - Plugin options
@@ -124,4 +258,29 @@ export declare function discoveryFastifyPlugin(fastify: unknown, options: {
     config: DiscoveryConfig;
     path?: string;
 }): Promise<void>;
+/**
+ * BREAKING CHANGES v1.2.3 → v2.0.0:
+ *
+ * 1. Discovery Endpoint Path
+ *    - OLD: /.well-known/lafs.json
+ *    - NEW: /.well-known/agent-card.json
+ *    - MIGRATION: Update client code to use new path
+ *    - BACKWARD COMPAT: Legacy path still works but logs deprecation warning
+ *
+ * 2. Discovery Document Format
+ *    - OLD: DiscoveryDocument interface (lafs_version, service, capabilities, endpoints)
+ *    - NEW: AgentCard interface (A2A v1.0 compliant)
+ *    - MIGRATION: Update config from 'service' to 'agent' format
+ *    - BACKWARD COMPAT: Legacy config format automatically converted with warning
+ *
+ * 3. Type Names
+ *    - Capability → AgentSkill (renamed to align with A2A spec)
+ *    - ServiceConfig → AgentCard (renamed)
+ *    - All old types marked as @deprecated
+ *
+ * 4. Removed in v2.0.0
+ *    - Legacy path support will be removed
+ *    - Old type definitions will be removed
+ *    - Automatic config migration will be removed
+ */
 export default discoveryMiddleware;