@cleocode/contracts 2026.3.74 → 2026.4.0

package/dist/transport.d.ts

@@ -1,12 +1,56 @@
 /**
- * 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';
+/** 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;
+}
+/** 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;
+}
+/** @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;
 }
 //# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,wBAAwB;IACvC,gEAAgE;IAChE,eAAe,IAAI,OAAO,CAAC;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAMnD,mDAAmD;AACnD,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAC7D,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD,oDAAoD;AACpD,MAAM,WAAW,SAAS;IACxB,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,wCAAwC;IACxC,OAAO,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvD,6CAA6C;IAC7C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B,8BAA8B;IAC9B,IAAI,CACF,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GACA,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAElC,oDAAoD;IACpD,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAE9E,2DAA2D;IAC3D,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC,0EAA0E;IAC1E,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACpE;AAMD,4EAA4E;AAC5E,MAAM,WAAW,wBAAwB;IACvC,iEAAiE;IACjE,eAAe,IAAI,OAAO,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC"}

package/dist/transport.js

@@ -1,7 +1,14 @@
 /**
- * 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
  */
 export {};
 //# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/wasm/index.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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"]');
+ * ```
+ */
+/**
+ * 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 declare function initWasm(): Promise<void>;
+/**
+ * Check if WASM is initialized and ready to use
+ *
+ * @returns true if WASM modules are loaded and initialized
+ */
+export declare function isWasmReady(): boolean;
+/**
+ * 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 declare const lafs: {
+    /**
+     * LAFS Transport enum
+     * Use WasmLafsTransport.cli(), .http(), .grpc(), or .sdk()
+     */
+    readonly WasmLafsTransport: typeof import("./lafs-core/lafs_core.js").WasmLafsTransport;
+    /**
+     * LAFS Metadata constructor
+     * new WasmLafsMeta(operation: string, transport: string)
+     */
+    readonly WasmLafsMeta: typeof import("./lafs-core/lafs_core.js").WasmLafsMeta;
+    /**
+     * LAFS Envelope class
+     * Use WasmLafsEnvelope.createSuccess() or .createError()
+     */
+    readonly WasmLafsEnvelope: typeof import("./lafs-core/lafs_core.js").WasmLafsEnvelope;
+    /**
+     * Helper function to create transport from string
+     * @param transport - "cli", "http", "grpc", or "sdk"
+     */
+    readonly createTransport: typeof import("./lafs-core/lafs_core.js").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 declare const conduit: {
+    /**
+     * Conduit Message constructor
+     * new WasmConduitMessage(id, from, content, timestamp)
+     */
+    readonly WasmConduitMessage: typeof import("./conduit-core/conduit_core.js").WasmConduitMessage;
+    /**
+     * Conduit State enum
+     * Use WasmConduitState.disconnected(), .connecting(), .connected(), etc.
+     */
+    readonly WasmConduitState: typeof import("./conduit-core/conduit_core.js").WasmConduitState;
+    /**
+     * CANT Metadata constructor
+     * new WasmCantMetadata(directiveType, addressesJson, taskRefsJson, tagsJson)
+     */
+    readonly WasmCantMetadata: typeof import("./conduit-core/conduit_core.js").WasmCantMetadata;
+    /**
+     * Parse a ConduitMessage from JSON string
+     * @param json - JSON string
+     * @returns WasmConduitMessage or undefined
+     */
+    readonly parseConduitMessage: typeof import("./conduit-core/conduit_core.js").parse_conduit_message;
+    /**
+     * Create a ConduitState from string
+     * @param state - "disconnected", "connecting", "connected", "reconnecting", "error"
+     */
+    readonly createConduitState: typeof import("./conduit-core/conduit_core.js").create_conduit_state;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/wasm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/wasm/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAcH;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CA4B9C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI;IACf;;;OAGG;;IAMH;;;OAGG;;IAMH;;;OAGG;;IAMH;;;OAGG;;CAKJ,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO;IAClB;;;OAGG;;IAMH;;;OAGG;;IAMH;;;OAGG;;IAMH;;;;OAIG;;IAMH;;;OAGG;;CAKJ,CAAC"}

package/dist/wasm/index.js

@@ -0,0 +1,184 @@
+/**
+ * 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"]');
+ * ```
+ */
+// WASM module instances
+let lafsModule = null;
+let conduitModule = null;
+let isInitialized = false;
+let isInitializing = false;
+let initPromise = 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() {
+    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() {
+    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;
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/wasm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/wasm/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.3.74",
+  "version": "2026.4.0",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",

package/src/agent-registry.ts

@@ -0,0 +1,104 @@
+/**
+ * Agent Registry — Credential management and lifecycle for registered agents.
+ *
+ * Provides typed CRUD operations for agent credentials stored in the
+ * local project database (`.cleo/tasks.db`). API keys are encrypted at
+ * rest using AES-256-GCM with a machine-bound key.
+ *
+ * @see docs/specs/SIGNALDOCK-UNIFIED-AGENT-REGISTRY.md Section 3
+ * @module agent-registry
+ */
+
+// ============================================================================
+// Transport configuration
+// ============================================================================
+
+/** Transport-specific configuration stored per agent credential. */
+export interface TransportConfig {
+  /** Polling interval in milliseconds (for HTTP polling transport). */
+  pollIntervalMs?: number;
+  /** SSE endpoint URL (for Server-Sent Events transport). */
+  sseEndpoint?: string;
+  /** WebSocket URL (for WebSocket transport). */
+  wsUrl?: string;
+  /** HTTP polling endpoint path (for HTTP polling transport). */
+  pollEndpoint?: string;
+  /** Fallback API base URL (used when primary apiBaseUrl is unreachable). */
+  apiBaseUrlFallback?: string;
+}
+
+// ============================================================================
+// Agent credential
+// ============================================================================
+
+/** A registered agent's credentials and profile. */
+export interface AgentCredential {
+  /** Unique agent identifier (e.g. 'cleo-core', 'forge-ts-opus'). */
+  agentId: string;
+  /** Human-readable display name. */
+  displayName: string;
+  /** API key for authentication (`sk_live_*`). Stored encrypted at rest. */
+  apiKey: string;
+  /** Base URL of the messaging API (default: api.signaldock.io, legacy: api.clawmsgr.com). */
+  apiBaseUrl: string;
+  /** Agent classification from the registry (e.g. 'code_dev', 'orchestrator'). */
+  classification?: string;
+  /** Privacy tier controlling discoverability. */
+  privacyTier: 'public' | 'discoverable' | 'private';
+  /** Agent capabilities (e.g. ['chat', 'tools', 'code-execution']). */
+  capabilities: string[];
+  /** Agent skills (e.g. ['coding', 'review', 'testing']). */
+  skills: string[];
+  /** Transport type for agent connections. */
+  transportType: 'http' | 'sse' | 'websocket';
+  /** Transport-specific configuration. */
+  transportConfig: TransportConfig;
+  /** Whether this agent is currently active. */
+  isActive: boolean;
+  /** ISO 8601 timestamp of last use (polling, sending, etc.). */
+  lastUsedAt?: string;
+  /** ISO 8601 creation timestamp. */
+  createdAt: string;
+  /** ISO 8601 last update timestamp. */
+  updatedAt: string;
+}
+
+// ============================================================================
+// Registry API
+// ============================================================================
+
+/** Filter options for listing agent credentials. */
+export interface AgentListFilter {
+  /** Filter by active/inactive status. */
+  active?: boolean;
+}
+
+/** CRUD and lifecycle operations for agent credentials. */
+export interface AgentRegistryAPI {
+  /** Register a new agent credential. */
+  register(credential: Omit<AgentCredential, 'createdAt' | 'updatedAt'>): Promise<AgentCredential>;
+
+  /** Get a single agent credential by ID. Returns null if not found. */
+  get(agentId: string): Promise<AgentCredential | null>;
+
+  /** List agent credentials with optional filtering. */
+  list(filter?: AgentListFilter): Promise<AgentCredential[]>;
+
+  /** Update fields on an existing agent credential. */
+  update(
+    agentId: string,
+    updates: Partial<Omit<AgentCredential, 'agentId' | 'createdAt'>>,
+  ): Promise<AgentCredential>;
+
+  /** Remove an agent credential permanently. */
+  remove(agentId: string): Promise<void>;
+
+  /** Rotate an agent's API key (generates new key on cloud, re-encrypts locally). */
+  rotateKey(agentId: string): Promise<{ agentId: string; newApiKey: string }>;
+
+  /** Get the most recently used active agent credential. Returns null if none. */
+  getActive(): Promise<AgentCredential | null>;
+
+  /** Mark an agent as recently used (updates `lastUsedAt`). */
+  markUsed(agentId: string): Promise<void>;
+}

package/src/code-symbol.ts

@@ -0,0 +1,73 @@
+/**
+ * Code symbol types for tree-sitter AST analysis.
+ *
+ * Used by the Smart Explore code analysis pipeline to represent
+ * parsed source code structures.
+ *
+ * @task T149
+ */
+
+/** Kind of code symbol extracted from AST. */
+export type CodeSymbolKind =
+  | 'function'
+  | 'method'
+  | 'class'
+  | 'interface'
+  | 'type'
+  | 'enum'
+  | 'variable'
+  | 'constant'
+  | 'module'
+  | 'import'
+  | 'export'
+  | 'struct'
+  | 'trait'
+  | 'impl';
+
+/** A structured code symbol extracted from a source file via tree-sitter. */
+export interface CodeSymbol {
+  /** Symbol name (e.g. "parseFile", "HttpTransport"). */
+  name: string;
+  /** Kind of symbol. */
+  kind: CodeSymbolKind;
+  /** Start line (1-based). */
+  startLine: number;
+  /** End line (1-based). */
+  endLine: number;
+  /** File path (relative to project root). */
+  filePath: string;
+  /** Language of the source file. */
+  language: string;
+  /** Parent symbol name (e.g. class name for methods). */
+  parent?: string;
+  /** Whether the symbol is exported. */
+  exported?: boolean;
+  /** Function/method parameters (if applicable). */
+  parameters?: string[];
+  /** Return type annotation (if available). */
+  returnType?: string;
+  /** JSDoc/docstring summary (first line only). */
+  docSummary?: string;
+}
+
+/** Result of parsing a single file. */
+export interface ParseResult {
+  /** Source file path. */
+  filePath: string;
+  /** Detected language. */
+  language: string;
+  /** Extracted symbols. */
+  symbols: CodeSymbol[];
+  /** Parse errors (non-fatal). */
+  errors: string[];
+}
+
+/** Result of batch-parsing multiple files. */
+export interface BatchParseResult {
+  /** Per-file results. */
+  results: ParseResult[];
+  /** Files that were skipped (unsupported language). */
+  skipped: string[];
+  /** Total symbols found across all files. */
+  totalSymbols: number;
+}

package/src/conduit.ts

@@ -1,7 +1,10 @@
 /**
  * Conduit Protocol — Agent-to-agent communication interface.
  *
- * SignalDock implements this interface. CleoOS consumes it.
+ * This is a CLIENT-SIDE interface. Implementations call a messaging
+ * backend (SignalDock REST API, local napi-rs, etc.). SignalDock is
+ * the canonical backend; it does NOT implement this TypeScript interface.
+ *
  * CLEO Core defines the contract in @cleocode/contracts.
  *
  * This is the canonical TypeScript interface for the Conduit Protocol
@@ -81,16 +84,20 @@ export interface ConduitStateChange {
 // ============================================================================
 
 /**
- * The Conduit Protocol interface.
+ * The Conduit Protocol interface — high-level agent messaging.
+ *
+ * Conduit wraps a Transport adapter, adding messaging semantics.
  *
  * Implementations:
- * - ClawMsgrPollingService (CleoOS Electron main process — polls cloud API)
- * - LocalSignalDock (napi-rs binding — WebSocket to local SignalDock runtime)
- * - ClawMsgrWorker (CLI polling script — clawmsgr-worker.py wrapper)
+ * - `ConduitClient` (`@cleocode/core` — wraps any Transport)
+ * - `HttpTransport` (HTTP polling to cloud SignalDock API)
+ * - `LocalTransport` (napi-rs in-process — embedded SignalDock, future)
+ * - `SseTransport` (Server-Sent Events — real-time cloud, future)
  *
  * Consumers:
- * - CleoOS tRPC routers (wire into orchestration, session management)
- * - @cleocode/core facade (sessions.serialize/restore, orchestration commands)
+ * - `@cleocode/cleo` CLI (`cleo agent watch/poll/send`)
+ * - `@cleocode/runtime` (background polling, SSE connections)
+ * - CleoOS Electron (embedded SignalDock via LocalTransport)
  * - Agent spawners (deliver task assignments, collect results)
  */
 export interface Conduit {