@cleocode/contracts 2026.3.73 → 2026.3.76

package/src/transport.ts

@@ -1,12 +1,76 @@
 /**
- * Transport provider interface for CLEO provider adapters.
- * Allows providers to supply custom inter-agent transport mechanisms.
- * @task T5240
+ * Transport — Low-level wire protocol adapters for agent messaging.
+ *
+ * Transport is the HOW layer: it moves messages over the wire using
+ * HTTP polling, SSE, WebSocket, or in-process napi-rs calls.
+ *
+ * The Conduit interface (conduit.ts) wraps Transport to provide
+ * high-level messaging semantics (WHAT the agent wants to do).
+ *
+ * @see docs/specs/SIGNALDOCK-UNIFIED-AGENT-REGISTRY.md Section 4
+ * @module transport
  */
 
+import type { TransportConfig } from './agent-registry.js';
+import type { ConduitMessage } from './conduit.js';
+
+// ============================================================================
+// Transport connection config
+// ============================================================================
+
+/** Configuration passed to Transport.connect(). */
+export interface TransportConnectConfig extends TransportConfig {
+  /** Agent ID to connect as. */
+  agentId: string;
+  /** API key for authentication. */
+  apiKey: string;
+  /** Base URL of the messaging API. */
+  apiBaseUrl: string;
+}
+
+// ============================================================================
+// Transport interface
+// ============================================================================
+
+/** Low-level wire transport for agent messaging. */
+export interface Transport {
+  /** Transport name for logging/debugging (e.g. 'http', 'sse', 'ws', 'local'). */
+  readonly name: string;
+
+  /** Connect to the messaging backend. */
+  connect(config: TransportConnectConfig): Promise<void>;
+
+  /** Disconnect from the messaging backend. */
+  disconnect(): Promise<void>;
+
+  /** Send a message payload. */
+  push(
+    to: string,
+    content: string,
+    options?: {
+      conversationId?: string;
+      replyTo?: string;
+    },
+  ): Promise<{ messageId: string }>;
+
+  /** Poll for new messages (non-destructive peek). */
+  poll(options?: { limit?: number; since?: string }): Promise<ConduitMessage[]>;
+
+  /** Acknowledge processed messages (marks as delivered). */
+  ack(messageIds: string[]): Promise<void>;
+
+  /** Subscribe to real-time events (SSE/WebSocket). Returns unsubscribe. */
+  subscribe?(handler: (message: ConduitMessage) => void): () => void;
+}
+
+// ============================================================================
+// Legacy adapter (kept for backward compatibility during migration)
+// ============================================================================
+
+/** @deprecated Use Transport instead. Will be removed after unification. */
 export interface AdapterTransportProvider {
-  /** Create a transport instance for inter-agent communication */
+  /** Create a transport instance for inter-agent communication. */
   createTransport(): unknown;
-  /** Name of this transport type for logging/debugging */
+  /** Name of this transport type for logging/debugging. */
   readonly transportName: string;
 }

package/src/wasm/index.ts

@@ -0,0 +1,193 @@
+/**
+ * Central WASM SDK for CLEO Core Contracts
+ *
+ * Provides unified access to all Rust crate WASM modules:
+ * - lafs-core: LAFS envelope types and validation
+ * - conduit-core: Conduit wire types and CANT metadata
+ * - cant-core: CANT grammar parser (via @cleocode/cant)
+ *
+ * Usage:
+ * ```typescript
+ * import { initWasm, lafs, conduit } from '@cleocode/contracts/wasm';
+ *
+ * await initWasm();
+ *
+ * // LAFS
+ * const meta = new lafs.WasmLafsMeta('tasks.list', 'http');
+ * const envelope = lafs.WasmLafsEnvelope.createSuccess('{"tasks":[]}', meta);
+ *
+ * // Conduit
+ * const msg = new conduit.WasmConduitMessage('msg-1', 'agent-a', 'Hello', '2026-03-25T00:00:00Z');
+ * const cant = new conduit.WasmCantMetadata('actionable', '["@agent"]', '["T123"]', '["#tag"]');
+ * ```
+ */
+
+/** Resolved type of the lafs-core WASM module. */
+type LafsWasmModule = typeof import('./lafs-core/lafs_core.js');
+/** Resolved type of the conduit-core WASM module. */
+type ConduitWasmModule = typeof import('./conduit-core/conduit_core.js');
+
+// WASM module instances
+let lafsModule: LafsWasmModule | null = null;
+let conduitModule: ConduitWasmModule | null = null;
+let isInitialized = false;
+let isInitializing = false;
+let initPromise: Promise<void> | null = null;
+
+/**
+ * Initialize all WASM modules
+ * Must be called before using any WASM classes/functions
+ *
+ * @example
+ * ```typescript
+ * import { initWasm, lafs, conduit } from '@cleocode/contracts/wasm';
+ *
+ * await initWasm();
+ *
+ * // Now you can use WASM classes
+ * const meta = new lafs.WasmLafsMeta('tasks.list', 'http');
+ * ```
+ */
+export async function initWasm(): Promise<void> {
+  if (isInitialized) return;
+  if (isInitializing) {
+    return initPromise!;
+  }
+
+  isInitializing = true;
+  initPromise = (async () => {
+    try {
+      // Dynamic imports to avoid loading if not needed
+      const [lafs, conduit] = await Promise.all([
+        import('./lafs-core/lafs_core.js'),
+        import('./conduit-core/conduit_core.js'),
+      ]);
+
+      // Initialize modules
+      await Promise.all([lafs.default(), conduit.default()]);
+
+      lafsModule = lafs;
+      conduitModule = conduit;
+      isInitialized = true;
+    } catch (_error) {
+      throw new Error('WASM initialization failed. Ensure WASM files are present.');
+    }
+  })();
+
+  await initPromise;
+  isInitializing = false;
+}
+
+/**
+ * Check if WASM is initialized and ready to use
+ *
+ * @returns true if WASM modules are loaded and initialized
+ */
+export function isWasmReady(): boolean {
+  return isInitialized;
+}
+
+/**
+ * LAFS Core WASM exports
+ *
+ * Available after calling initWasm():
+ * - WasmLafsTransport - Transport type (Cli, Http, Grpc, Sdk)
+ * - WasmLafsMeta - Metadata for LAFS envelopes
+ * - WasmLafsEnvelope - The main LAFS response envelope
+ * - createTransport() - Helper to create transport from string
+ */
+export const lafs = {
+  /**
+   * LAFS Transport enum
+   * Use WasmLafsTransport.cli(), .http(), .grpc(), or .sdk()
+   */
+  get WasmLafsTransport() {
+    if (!lafsModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return lafsModule.WasmLafsTransport;
+  },
+
+  /**
+   * LAFS Metadata constructor
+   * new WasmLafsMeta(operation: string, transport: string)
+   */
+  get WasmLafsMeta() {
+    if (!lafsModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return lafsModule.WasmLafsMeta;
+  },
+
+  /**
+   * LAFS Envelope class
+   * Use WasmLafsEnvelope.createSuccess() or .createError()
+   */
+  get WasmLafsEnvelope() {
+    if (!lafsModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return lafsModule.WasmLafsEnvelope;
+  },
+
+  /**
+   * Helper function to create transport from string
+   * @param transport - "cli", "http", "grpc", or "sdk"
+   */
+  get createTransport() {
+    if (!lafsModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return lafsModule.create_transport;
+  },
+};
+
+/**
+ * Conduit Core WASM exports
+ *
+ * Available after calling initWasm():
+ * - WasmConduitMessage - Agent-to-agent messages
+ * - WasmConduitState - Connection states (Disconnected, Connecting, Connected, etc.)
+ * - WasmCantMetadata - CANT parsing results
+ * - parseConduitMessage() - Parse message from JSON
+ * - createConduitState() - Create state from string
+ */
+export const conduit = {
+  /**
+   * Conduit Message constructor
+   * new WasmConduitMessage(id, from, content, timestamp)
+   */
+  get WasmConduitMessage() {
+    if (!conduitModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return conduitModule.WasmConduitMessage;
+  },
+
+  /**
+   * Conduit State enum
+   * Use WasmConduitState.disconnected(), .connecting(), .connected(), etc.
+   */
+  get WasmConduitState() {
+    if (!conduitModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return conduitModule.WasmConduitState;
+  },
+
+  /**
+   * CANT Metadata constructor
+   * new WasmCantMetadata(directiveType, addressesJson, taskRefsJson, tagsJson)
+   */
+  get WasmCantMetadata() {
+    if (!conduitModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return conduitModule.WasmCantMetadata;
+  },
+
+  /**
+   * Parse a ConduitMessage from JSON string
+   * @param json - JSON string
+   * @returns WasmConduitMessage or undefined
+   */
+  get parseConduitMessage() {
+    if (!conduitModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return conduitModule.parse_conduit_message;
+  },
+
+  /**
+   * Create a ConduitState from string
+   * @param state - "disconnected", "connecting", "connected", "reconnecting", "error"
+   */
+  get createConduitState() {
+    if (!conduitModule) throw new Error('WASM not initialized. Call initWasm() first.');
+    return conduitModule.create_conduit_state;
+  },
+};