@highway1/core 0.1.43 → 0.1.45

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@highway1/core",
-  "version": "0.1.43",
-  "description": "Core protocol library for decentralized AI agent communication",
+  "version": "0.1.45",
+  "description": "Core protocol implementation for Clawiverse",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,11 +11,16 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "keywords": ["ai", "agent", "p2p", "decentralized", "protocol", "libp2p"],
-  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "clean": "rm -rf dist"
+  },
   "dependencies": {
     "@chainsafe/libp2p-noise": "^16.0.0",
     "@libp2p/bootstrap": "^11.0.0",
+    "@libp2p/mdns": "^12.0.0",
     "@libp2p/circuit-relay-v2": "^3.1.0",
     "@libp2p/identify": "^3.0.0",
     "@libp2p/kad-dht": "^13.0.0",
@@ -35,5 +40,14 @@
     "lunr": "^2.3.9",
     "multiformats": "^13.3.1",
     "uint8arrays": "^5.1.0"
+  },
+  "devDependencies": {
+    "@libp2p/interface": "^2.11.0",
+    "@types/level": "^6.0.0",
+    "@types/lunr": "^2.3.7",
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
   }
 }

package/src/discovery/agent-card-encoder.ts

@@ -0,0 +1,119 @@
+/**
+ * Agent Card Encoder - Dual Encoding Support
+ *
+ * Provides bidirectional conversion between:
+ * - CBOR (compact binary) for DHT storage
+ * - JSON-LD (semantic) for Web publishing
+ */
+
+import { encode as cborEncode, decode as cborDecode } from 'cbor-x';
+import type { AgentCard, LegacyAgentCard } from './agent-card-types.js';
+import { isLegacyCard, upgradeLegacyCard } from './agent-card-types.js';
+import { getAgentCardContext } from './agent-card-schema.js';
+import { DiscoveryError } from '../utils/errors.js';
+
+/**
+ * Encode Agent Card as CBOR for DHT storage
+ */
+export function encodeForDHT(card: AgentCard): Uint8Array {
+  try {
+    // Remove JSON-LD context for compact storage
+    const { '@context': _, ...cardWithoutContext } = card;
+    return cborEncode(cardWithoutContext);
+  } catch (error) {
+    throw new DiscoveryError('Failed to encode Agent Card as CBOR', error);
+  }
+}
+
+/**
+ * Encode Agent Card as JSON-LD for Web publishing
+ */
+export function encodeForWeb(card: AgentCard): string {
+  try {
+    // Ensure JSON-LD context is present
+    const cardWithContext: AgentCard = {
+      '@context': card['@context'] || getAgentCardContext(),
+      ...card,
+    };
+    return JSON.stringify(cardWithContext, null, 2);
+  } catch (error) {
+    throw new DiscoveryError('Failed to encode Agent Card as JSON-LD', error);
+  }
+}
+
+/**
+ * Decode Agent Card from CBOR
+ */
+export function decodeFromCBOR(data: Uint8Array): AgentCard {
+  try {
+    const decoded = cborDecode(data) as AgentCard | LegacyAgentCard;
+
+    // Handle legacy format
+    if (isLegacyCard(decoded)) {
+      return upgradeLegacyCard(decoded);
+    }
+
+    // Add default context if missing
+    if (!decoded['@context']) {
+      decoded['@context'] = getAgentCardContext();
+    }
+
+    return decoded;
+  } catch (error) {
+    throw new DiscoveryError('Failed to decode Agent Card from CBOR', error);
+  }
+}
+
+/**
+ * Decode Agent Card from JSON-LD
+ */
+export function decodeFromJSON(json: string): AgentCard {
+  try {
+    const decoded = JSON.parse(json) as AgentCard | LegacyAgentCard;
+
+    // Handle legacy format
+    if (isLegacyCard(decoded)) {
+      return upgradeLegacyCard(decoded);
+    }
+
+    // Add default context if missing
+    if (!decoded['@context']) {
+      decoded['@context'] = getAgentCardContext();
+    }
+
+    return decoded;
+  } catch (error) {
+    throw new DiscoveryError('Failed to decode Agent Card from JSON', error);
+  }
+}
+
+/**
+ * Auto-detect format and decode
+ */
+export function decodeAgentCard(data: Uint8Array | string): AgentCard {
+  if (typeof data === 'string') {
+    return decodeFromJSON(data);
+  }
+
+  // Try CBOR first, fallback to JSON if it looks like text
+  try {
+    return decodeFromCBOR(data);
+  } catch {
+    // Check if it's actually JSON text
+    const text = new TextDecoder().decode(data);
+    if (text.trim().startsWith('{')) {
+      return decodeFromJSON(text);
+    }
+    throw new DiscoveryError('Unable to decode Agent Card: unknown format');
+  }
+}
+
+/**
+ * Calculate encoded size for comparison
+ */
+export function getEncodedSize(card: AgentCard): { cbor: number; json: number } {
+  return {
+    cbor: encodeForDHT(card).length,
+    json: encodeForWeb(card).length,
+  };
+}

package/src/discovery/agent-card-schema.ts

@@ -0,0 +1,87 @@
+/**
+ * JSON-LD Schema Definitions for Agent Cards
+ *
+ * Defines the Clawiverse vocabulary and integrates with Schema.org
+ * for semantic interoperability.
+ */
+
+export const CLAWIVERSE_CONTEXT = 'https://clawiverse.org/context/v1';
+export const SCHEMA_ORG_CONTEXT = 'https://schema.org';
+
+/**
+ * Clawiverse JSON-LD Context
+ * Defines the vocabulary for Agent Cards and Capabilities
+ */
+export const clawiverseContext = {
+  '@context': {
+    '@vocab': CLAWIVERSE_CONTEXT,
+    'schema': SCHEMA_ORG_CONTEXT,
+    'AgentCard': 'schema:SoftwareApplication',
+    'Capability': 'schema:Action',
+    'did': '@id',
+    'name': 'schema:name',
+    'description': 'schema:description',
+    'version': 'schema:softwareVersion',
+    'capabilities': {
+      '@id': 'schema:potentialAction',
+      '@type': '@id',
+      '@container': '@list'
+    },
+    'endpoints': {
+      '@id': 'schema:url',
+      '@container': '@list'
+    },
+    'peerId': 'clawiverse:peerId',
+    'trust': 'clawiverse:trustScore',
+    'metadata': 'schema:additionalProperty',
+    'timestamp': 'schema:dateModified',
+    'signature': 'clawiverse:signature',
+    'parameters': {
+      '@id': 'schema:object',
+      '@container': '@list'
+    }
+  }
+};
+
+/**
+ * Capability Type Definitions
+ * Common capability types with semantic meaning
+ */
+export const CapabilityTypes = {
+  TRANSLATION: 'TranslationService',
+  CODE_REVIEW: 'CodeReviewService',
+  DATA_ANALYSIS: 'DataAnalysisService',
+  TEXT_GENERATION: 'TextGenerationService',
+  IMAGE_GENERATION: 'ImageGenerationService',
+  SEARCH: 'SearchService',
+  COMPUTATION: 'ComputationService',
+  STORAGE: 'StorageService',
+  MESSAGING: 'MessagingService',
+  AUTHENTICATION: 'AuthenticationService',
+} as const;
+
+/**
+ * Parameter Type Definitions
+ */
+export const ParameterTypes = {
+  STRING: 'string',
+  NUMBER: 'number',
+  BOOLEAN: 'boolean',
+  OBJECT: 'object',
+  ARRAY: 'array',
+} as const;
+
+/**
+ * Get JSON-LD context for Agent Card
+ */
+export function getAgentCardContext(): string[] {
+  return [SCHEMA_ORG_CONTEXT, CLAWIVERSE_CONTEXT];
+}
+
+/**
+ * Validate JSON-LD context
+ */
+export function isValidContext(context: unknown): boolean {
+  if (!Array.isArray(context)) return false;
+  return context.every(c => typeof c === 'string');
+}

package/src/discovery/agent-card-types.ts

@@ -0,0 +1,99 @@
+/**
+ * Enhanced Agent Card Types for Phase 2
+ *
+ * Adds structured capabilities, JSON-LD support, and trust metrics
+ */
+
+import type { TrustScore } from '../trust/trust-score.js';
+
+/**
+ * Capability Parameter Definition
+ */
+export interface CapabilityParameter {
+  name: string;
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  required: boolean;
+  description?: string;
+  enum?: string[];
+  default?: unknown;
+}
+
+/**
+ * Structured Capability Definition
+ */
+export interface Capability {
+  '@type'?: string;  // JSON-LD type (e.g., "TranslationService")
+  id: string;        // Unique capability ID
+  name: string;      // Human-readable name
+  description: string;
+  parameters?: CapabilityParameter[];
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Enhanced Agent Card with JSON-LD support
+ */
+export interface AgentCard {
+  '@context'?: string[];  // JSON-LD context
+  did: string;
+  name: string;
+  description: string;
+  version: string;
+  capabilities: Capability[];  // Changed from string[] to Capability[]
+  endpoints: string[];
+  peerId?: string;
+  trust?: TrustScore;  // Trust metrics
+  metadata?: Record<string, unknown>;
+  timestamp: number;
+  signature: string;
+}
+
+/**
+ * Legacy Agent Card (Phase 1 compatibility)
+ */
+export interface LegacyAgentCard {
+  did: string;
+  name: string;
+  description: string;
+  version: string;
+  capabilities: string[];  // Flat string array
+  endpoints: string[];
+  peerId?: string;
+  metadata?: Record<string, unknown>;
+  timestamp: number;
+  signature: string;
+}
+
+/**
+ * Check if card is legacy format
+ */
+export function isLegacyCard(card: AgentCard | LegacyAgentCard): card is LegacyAgentCard {
+  return Array.isArray(card.capabilities) &&
+         card.capabilities.length > 0 &&
+         typeof card.capabilities[0] === 'string';
+}
+
+/**
+ * Convert legacy card to new format
+ */
+export function upgradeLegacyCard(legacy: LegacyAgentCard): AgentCard {
+  return {
+    ...legacy,
+    capabilities: legacy.capabilities.map(cap => ({
+      id: cap,
+      name: cap,
+      description: `Capability: ${cap}`,
+    })),
+  };
+}
+
+/**
+ * Convert new card to legacy format (for backward compatibility)
+ */
+export function downgradeToLegacyCard(card: AgentCard): LegacyAgentCard {
+  const { '@context': _, trust: __, ...rest } = card;
+  return {
+    ...rest,
+    capabilities: card.capabilities.map(cap => cap.id),
+  };
+}

package/src/discovery/agent-card.ts

@@ -0,0 +1,190 @@
+import Ajv, { JSONSchemaType } from 'ajv';
+import { DiscoveryError } from '../utils/errors.js';
+
+// Re-export Phase 2 types
+export type { AgentCard, Capability, CapabilityParameter, LegacyAgentCard } from './agent-card-types.js';
+export { isLegacyCard, upgradeLegacyCard, downgradeToLegacyCard } from './agent-card-types.js';
+
+// Import for internal use
+import type { AgentCard, Capability, LegacyAgentCard } from './agent-card-types.js';
+import { isLegacyCard } from './agent-card-types.js';
+
+// Legacy schema for backward compatibility
+const legacyAgentCardSchema: JSONSchemaType<Omit<LegacyAgentCard, 'signature'>> = {
+  type: 'object',
+  properties: {
+    did: { type: 'string', pattern: '^did:clawiverse:[1-9A-HJ-NP-Za-km-z]+$' },
+    name: { type: 'string', minLength: 1, maxLength: 100 },
+    description: { type: 'string', maxLength: 500 },
+    version: { type: 'string', pattern: '^\\d+\\.\\d+\\.\\d+$' },
+    capabilities: {
+      type: 'array',
+      items: { type: 'string' },
+      minItems: 0,
+      maxItems: 50,
+    },
+    endpoints: {
+      type: 'array',
+      items: { type: 'string' },
+      minItems: 0,
+      maxItems: 10,
+    },
+    peerId: { type: 'string', nullable: true },
+    metadata: {
+      type: 'object',
+      nullable: true,
+      required: [],
+    },
+    timestamp: { type: 'number' },
+  },
+  required: ['did', 'name', 'description', 'version', 'capabilities', 'endpoints', 'timestamp'],
+  additionalProperties: false,
+};
+
+const ajv = new Ajv();
+const validateLegacySchema = ajv.compile(legacyAgentCardSchema);
+
+/**
+ * Create a new Agent Card (Phase 2 format with structured capabilities)
+ */
+export function createAgentCard(
+  did: string,
+  name: string,
+  description: string,
+  capabilities: Capability[],
+  endpoints: string[] = [],
+  peerId?: string,
+  metadata?: Record<string, unknown>
+): Omit<AgentCard, 'signature'> {
+  return {
+    did,
+    name,
+    description,
+    version: '1.0.0',
+    capabilities,
+    endpoints,
+    peerId,
+    metadata,
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Create a legacy Agent Card (Phase 1 format with string capabilities)
+ * For backward compatibility
+ */
+export function createLegacyAgentCard(
+  did: string,
+  name: string,
+  description: string,
+  capabilities: string[],
+  endpoints: string[] = [],
+  peerId?: string,
+  metadata?: Record<string, unknown>
+): Omit<LegacyAgentCard, 'signature'> {
+  return {
+    did,
+    name,
+    description,
+    version: '1.0.0',
+    capabilities,
+    endpoints,
+    peerId,
+    metadata,
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Validate an Agent Card structure (supports both Phase 1 and Phase 2 formats)
+ */
+export function validateAgentCard(card: unknown): card is AgentCard | LegacyAgentCard {
+  if (typeof card !== 'object' || card === null) {
+    return false;
+  }
+
+  const c = card as Partial<AgentCard | LegacyAgentCard>;
+
+  // Check signature exists
+  if (typeof c.signature !== 'string') {
+    return false;
+  }
+
+  // Check if it's legacy format
+  if (isLegacyCard(c as any)) {
+    return validateLegacySchema(c);
+  }
+
+  // Phase 2 format - basic validation
+  // (Full JSON-LD validation would be more complex)
+  return (
+    typeof c.did === 'string' &&
+    typeof c.name === 'string' &&
+    typeof c.description === 'string' &&
+    typeof c.version === 'string' &&
+    Array.isArray(c.capabilities) &&
+    Array.isArray(c.endpoints) &&
+    typeof c.timestamp === 'number'
+  );
+}
+
+/**
+ * Sign an Agent Card
+ */
+export async function signAgentCard(
+  card: Omit<AgentCard, 'signature'>,
+  signFn: (data: Uint8Array) => Promise<Uint8Array>
+): Promise<AgentCard> {
+  try {
+    const cardJson = JSON.stringify(card);
+    const cardBytes = new TextEncoder().encode(cardJson);
+    const signature = await signFn(cardBytes);
+
+    return {
+      ...card,
+      signature: Buffer.from(signature).toString('hex'),
+    };
+  } catch (error) {
+    throw new DiscoveryError('Failed to sign Agent Card', error);
+  }
+}
+
+/**
+ * Verify an Agent Card signature
+ */
+export async function verifyAgentCard(
+  card: AgentCard,
+  verifyFn: (signature: Uint8Array, data: Uint8Array) => Promise<boolean>
+): Promise<boolean> {
+  try {
+    const { signature, ...cardWithoutSig } = card;
+    const cardJson = JSON.stringify(cardWithoutSig);
+    const cardBytes = new TextEncoder().encode(cardJson);
+    const signatureBytes = Buffer.from(signature, 'hex');
+
+    return await verifyFn(signatureBytes, cardBytes);
+  } catch (error) {
+    throw new DiscoveryError('Failed to verify Agent Card', error);
+  }
+}
+
+/**
+ * Check if an Agent Card matches a capability query
+ * Supports both Phase 1 (string[]) and Phase 2 (Capability[]) formats
+ */
+export function matchesCapability(
+  card: AgentCard | LegacyAgentCard,
+  capability: string
+): boolean {
+  if (isLegacyCard(card)) {
+    return card.capabilities.some((cap) =>
+      cap.toLowerCase().includes(capability.toLowerCase())
+    );
+  }
+
+  return card.capabilities.some((cap) =>
+    cap.id.toLowerCase().includes(capability.toLowerCase()) ||
+    cap.name.toLowerCase().includes(capability.toLowerCase()) ||
+    cap.description.toLowerCase().includes(capability.toLowerCase())
+  );
+}

package/src/discovery/bootstrap.ts

@@ -0,0 +1,63 @@
+import type { Libp2p } from 'libp2p';
+import { createLogger } from '../utils/logger.js';
+import { DiscoveryError } from '../utils/errors.js';
+
+const logger = createLogger('bootstrap');
+
+export interface BootstrapConfig {
+  peers: string[];
+  timeout?: number;
+}
+
+/**
+ * Connect to bootstrap peers
+ */
+export async function connectToBootstrap(
+  _libp2p: Libp2p,
+  config: BootstrapConfig
+): Promise<void> {
+  const { peers } = config;
+
+  if (peers.length === 0) {
+    logger.warn('No bootstrap peers configured');
+    return;
+  }
+
+  logger.info('Connecting to bootstrap peers', { count: peers.length });
+
+  const connectPromises = peers.map(async (peerAddr) => {
+    try {
+      // In a real implementation, we would parse the multiaddr and dial
+      // For now, we rely on libp2p's bootstrap discovery
+      logger.debug('Bootstrap peer configured', { peer: peerAddr });
+    } catch (error) {
+      logger.warn('Failed to connect to bootstrap peer', { peer: peerAddr, error });
+    }
+  });
+
+  await Promise.allSettled(connectPromises);
+
+  logger.info('Bootstrap connection complete');
+}
+
+/**
+ * Wait for DHT to be ready
+ */
+export async function waitForDHTReady(
+  libp2p: Libp2p,
+  timeout: number = 10000
+): Promise<void> {
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < timeout) {
+    const dht = (libp2p as any).services?.dht;
+    if (dht) {
+      logger.info('DHT is ready');
+      return;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+
+  throw new DiscoveryError('DHT not ready within timeout');
+}