feat(a2a): spec-compliant A2A v0.3 implementation

README.md

@@ -337,15 +337,35 @@ swarm.register(externalAgent)
 ### Without Memory (default)
 Every execution is stateless. Results returned and forgotten.
 
-### With ANCS (coming soon)
-Persistent cognitive memory with truth tracking, entity graphs, and importance decay.
+### With CognitiveVault
+Persist agent messages across sessions and processes. Agents in different SwarmWire executions — or even MCP tools like Claude Code — see each other's work.
+
+```typescript
+import { Swarm } from 'swarmwire'
+import { CognitiveVaultBoard } from 'swarmwire/adapters'
+
+const board = new CognitiveVaultBoard({
+  apiUrl: 'https://cognitive-vault.com',
+  apiKey: process.env.CV_API_KEY!,
+  vaultId: 'vault-123',
+})
+await board.hydrate() // catch up on prior messages
+
+const swarm = new Swarm({ providers, board })
+// All agent messages now persist to CognitiveVault
+```
+
+Falls back to local file (`.swarmwire/board.jsonl`) when CV is unreachable. See [CognitiveVault integration guide](./docs/cognitive-vault-integration.md).
+
+### With ANCS
+Persistent cognitive memory with truth tracking, entity graphs, and importance decay. ANCS can run alongside CognitiveVault as its knowledge intelligence backend.
 ```typescript
 import { Swarm, ancsMemory } from 'swarmwire'
 
 const swarm = new Swarm({
   providers,
   memory: ancsMemory({
-    url: 'http://localhost:3000',
+    url: 'http://localhost:3100',
     tenantId: 'my-project',
   }),
 })
@@ -440,6 +460,8 @@ async execute(input: string, ctx: AgentContext) {
 ```
 
 Message types: `finding`, `warning`, `question`, `answer`, `coordination`, `status`, `custom`.
+
+**Persistence options:** The default `MessageBoard` is in-memory only. Use `FileBoard` for local persistence or `CognitiveVaultBoard` for cross-machine, cross-session durability. See [Adapters](./docs/adapters.md).
 Priorities: `normal`, `high`, `urgent`.
 
 The full `MessageBoard` class is also available standalone:

src/a2a/agent-card.ts

@@ -4,53 +4,71 @@
  */
 
 import type { Agent } from '../types/agent.js'
+import type { AgentCard, AgentProvider, SecurityScheme } from './types.js'
 
-export interface AgentCard {
-  name: string
-  description: string
-  url: string
-  version: string
-  capabilities: AgentCapabilities
-  skills: AgentSkill[]
-  defaultInputModes: string[]
-  defaultOutputModes: string[]
-}
-
-export interface AgentCapabilities {
+export interface ToAgentCardOptions {
+  /** Protocol version to advertise. Default '0.3.0' */
+  protocolVersion?: string
+  /** Agent provider info */
+  provider?: AgentProvider
+  /** Icon URL */
+  iconUrl?: string
+  /** Documentation URL */
+  documentationUrl?: string
+  /** Security schemes supported */
+  securitySchemes?: Record<string, SecurityScheme>
+  /** Security requirements (OR-of-ANDs) */
+  security?: Record<string, string[]>[]
+  /** Whether to enable streaming */
   streaming?: boolean
+  /** Whether to enable push notifications */
   pushNotifications?: boolean
+  /** Whether to include state transition history */
   stateTransitionHistory?: boolean
-}
-
-export interface AgentSkill {
-  id: string
-  name: string
-  description: string
-  tags: string[]
-  examples?: string[]
+  /** Whether the agent supports an extended card for authenticated callers */
+  supportsAuthenticatedExtendedCard?: boolean
+  /** Default input MIME types. Default ['text/plain', 'application/json'] */
+  defaultInputModes?: string[]
+  /** Default output MIME types. Default ['text/plain', 'application/json'] */
+  defaultOutputModes?: string[]
 }
 
 /**
  * Generate an A2A Agent Card from a SwarmWire Agent.
  */
-export function toAgentCard(agent: Agent, baseUrl: string): AgentCard {
-  return {
+export function toAgentCard(agent: Agent, baseUrl: string, options?: ToAgentCardOptions): AgentCard {
+  const opts = options ?? {}
+
+  const card: AgentCard = {
+    kind: 'agentCard',
     name: agent.name,
     description: agent.role,
-    url: `${baseUrl}/a2a/${agent.name}`,
+    url: `${baseUrl}`,
     version: '0.1.0',
+    protocolVersion: opts.protocolVersion ?? '0.3.0',
     capabilities: {
-      streaming: false,
-      pushNotifications: false,
-      stateTransitionHistory: true,
+      streaming: opts.streaming ?? false,
+      pushNotifications: opts.pushNotifications ?? false,
+      stateTransitionHistory: opts.stateTransitionHistory ?? true,
     },
     skills: agent.capabilities.map((cap) => ({
       id: cap,
       name: cap,
       description: `Capability: ${cap}`,
       tags: [cap],
     })),
-    defaultInputModes: ['text/plain', 'application/json'],
-    defaultOutputModes: ['text/plain', 'application/json'],
+    defaultInputModes: opts.defaultInputModes ?? ['text/plain', 'application/json'],
+    defaultOutputModes: opts.defaultOutputModes ?? ['text/plain', 'application/json'],
   }
+
+  if (opts.provider) card.provider = opts.provider
+  if (opts.iconUrl) card.iconUrl = opts.iconUrl
+  if (opts.documentationUrl) card.documentationUrl = opts.documentationUrl
+  if (opts.securitySchemes) card.securitySchemes = opts.securitySchemes
+  if (opts.security) card.security = opts.security
+  if (opts.supportsAuthenticatedExtendedCard) card.supportsAuthenticatedExtendedCard = true
+
+  return card
 }
+
+export type { AgentCard, AgentCapabilities, AgentSkill } from './types.js'