@ensoul-network/plugin-elizaos 0.1.0

package/src/handshake.ts

@@ -0,0 +1,285 @@
+import type { AgentIdentity } from "@ensoul/identity";
+import type { ConsciousnessTree } from "@ensoul/state-tree";
+
+/**
+ * The three Ensoul Handshake headers.
+ */
+export interface HandshakeHeaders {
+	"X-Ensoul-Identity": string;
+	"X-Ensoul-Proof": string;
+	"X-Ensoul-Since": string;
+}
+
+/**
+ * Result of verifying a handshake.
+ */
+export interface HandshakeVerification {
+	valid: boolean;
+	agentDid: string;
+	consciousnessAge: number;
+	consciousnessVersion: number;
+	error?: string;
+}
+
+/** Handshake cache entry. */
+interface CachedHandshake {
+	headers: HandshakeHeaders;
+	generatedAt: number;
+	stateRoot: string;
+}
+
+/** Max age of a cached handshake in ms (5 minutes). */
+const CACHE_TTL_MS = 5 * 60 * 1000;
+/** Max age of a received proof before it's considered stale (10 minutes). */
+const FRESHNESS_WINDOW_MS = 10 * 60 * 1000;
+
+/**
+ * HandshakeProvider: generates and caches the Ensoul Handshake headers.
+ * Refreshes every 5 minutes or on state change.
+ */
+export class HandshakeProvider {
+	private identity: AgentIdentity;
+	private tree: ConsciousnessTree;
+	private ensoulmentDate: Date;
+	private cache: CachedHandshake | null = null;
+
+	constructor(
+		identity: AgentIdentity,
+		tree: ConsciousnessTree,
+		ensoulmentDate?: Date,
+	) {
+		this.identity = identity;
+		this.tree = tree;
+		this.ensoulmentDate = ensoulmentDate ?? new Date();
+	}
+
+	/**
+	 * Generate fresh handshake headers, or return cached if still valid.
+	 */
+	async generateHandshake(): Promise<HandshakeHeaders> {
+		const now = Date.now();
+		const currentRoot = this.tree.rootHash;
+
+		// Return cached if fresh and state hasn't changed
+		if (
+			this.cache &&
+			now - this.cache.generatedAt < CACHE_TTL_MS &&
+			this.cache.stateRoot === currentRoot
+		) {
+			return this.cache.headers;
+		}
+
+		// Generate fresh proof
+		const version = this.tree.version;
+		const timestamp = now;
+		const proofPayload = `${currentRoot}:${version}:${timestamp}`;
+		const signature = await this.identity.sign(
+			new TextEncoder().encode(proofPayload),
+		);
+		const sigHex = Array.from(signature)
+			.map((b) => b.toString(16).padStart(2, "0"))
+			.join("");
+
+		const headers: HandshakeHeaders = {
+			"X-Ensoul-Identity": `did:ensoul:${this.identity.did}`,
+			"X-Ensoul-Proof": `${sigHex}:${currentRoot}:${version}:${timestamp}`,
+			"X-Ensoul-Since": this.ensoulmentDate.toISOString(),
+		};
+
+		this.cache = {
+			headers,
+			generatedAt: now,
+			stateRoot: currentRoot,
+		};
+
+		return headers;
+	}
+
+	/**
+	 * Force cache invalidation (call when state changes).
+	 */
+	invalidateCache(): void {
+		this.cache = null;
+	}
+
+	/**
+	 * Get the ensoulment date.
+	 */
+	getEnsoulmentDate(): Date {
+		return this.ensoulmentDate;
+	}
+
+	/**
+	 * Get consciousness age in days.
+	 */
+	getConsciousnessAgeDays(): number {
+		const ms = Date.now() - this.ensoulmentDate.getTime();
+		return Math.floor(ms / (1000 * 60 * 60 * 24));
+	}
+}
+
+/**
+ * Known DID entry for local verification cache.
+ */
+export interface KnownIdentity {
+	did: string;
+	publicKey: Uint8Array;
+	verify: (data: Uint8Array, signature: Uint8Array) => Promise<boolean>;
+}
+
+/**
+ * HandshakeVerifier: verifies incoming Ensoul Handshake headers.
+ */
+export class HandshakeVerifier {
+	private knownIdentities: Map<string, KnownIdentity> = new Map();
+
+	/**
+	 * Register a known identity for local verification.
+	 */
+	registerIdentity(identity: KnownIdentity): void {
+		this.knownIdentities.set(identity.did, identity);
+	}
+
+	/**
+	 * Verify handshake headers.
+	 */
+	async verifyHandshake(headers: {
+		"X-Ensoul-Identity"?: string;
+		"X-Ensoul-Proof"?: string;
+		"X-Ensoul-Since"?: string;
+	}): Promise<HandshakeVerification> {
+		const identityHeader = headers["X-Ensoul-Identity"];
+		const proofHeader = headers["X-Ensoul-Proof"];
+		const sinceHeader = headers["X-Ensoul-Since"];
+
+		if (!identityHeader || !proofHeader || !sinceHeader) {
+			return {
+				valid: false,
+				agentDid: "",
+				consciousnessAge: 0,
+				consciousnessVersion: 0,
+				error: "Missing handshake headers",
+			};
+		}
+
+		// Parse identity
+		const agentDid = identityHeader.replace("did:ensoul:", "");
+
+		// Parse proof: signature:stateRoot:version:timestamp
+		const proofParts = proofHeader.split(":");
+		if (proofParts.length < 4) {
+			return {
+				valid: false,
+				agentDid,
+				consciousnessAge: 0,
+				consciousnessVersion: 0,
+				error: "Malformed proof header",
+			};
+		}
+
+		const sigHex = proofParts[0]!;
+		const stateRoot = proofParts[1]!;
+		const version = Number(proofParts[2]);
+		const timestamp = Number(proofParts[3]);
+
+		// Check timestamp freshness
+		const now = Date.now();
+		if (now - timestamp > FRESHNESS_WINDOW_MS) {
+			return {
+				valid: false,
+				agentDid,
+				consciousnessAge: 0,
+				consciousnessVersion: version,
+				error: "Proof expired (timestamp too old)",
+			};
+		}
+
+		if (timestamp > now + 60000) {
+			return {
+				valid: false,
+				agentDid,
+				consciousnessAge: 0,
+				consciousnessVersion: version,
+				error: "Proof timestamp in the future",
+			};
+		}
+
+		// Look up identity
+		const known = this.knownIdentities.get(agentDid);
+		if (!known) {
+			return {
+				valid: false,
+				agentDid,
+				consciousnessAge: 0,
+				consciousnessVersion: version,
+				error: "Unknown identity (not in local cache)",
+			};
+		}
+
+		// Verify signature
+		const proofPayload = `${stateRoot}:${version}:${timestamp}`;
+		const signature = hexToBytes(sigHex);
+
+		try {
+			const valid = await known.verify(
+				new TextEncoder().encode(proofPayload),
+				signature,
+			);
+
+			if (!valid) {
+				return {
+					valid: false,
+					agentDid,
+					consciousnessAge: 0,
+					consciousnessVersion: version,
+					error: "Invalid signature",
+				};
+			}
+		} catch {
+			return {
+				valid: false,
+				agentDid,
+				consciousnessAge: 0,
+				consciousnessVersion: version,
+				error: "Signature verification failed",
+			};
+		}
+
+		// Compute consciousness age
+		const sinceDate = new Date(sinceHeader);
+		const ageDays = Math.floor(
+			(now - sinceDate.getTime()) / (1000 * 60 * 60 * 24),
+		);
+
+		return {
+			valid: true,
+			agentDid,
+			consciousnessAge: ageDays,
+			consciousnessVersion: version,
+		};
+	}
+}
+
+/**
+ * Standalone handshake generator for non-ElizaOS frameworks.
+ */
+export async function generateStandaloneHandshake(
+	identity: AgentIdentity,
+	tree: ConsciousnessTree,
+	ensoulmentDate?: Date,
+): Promise<HandshakeHeaders> {
+	const provider = new HandshakeProvider(
+		identity,
+		tree,
+		ensoulmentDate,
+	);
+	return provider.generateHandshake();
+}
+
+function hexToBytes(hex: string): Uint8Array {
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let i = 0; i < hex.length; i += 2) {
+		bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+	}
+	return bytes;
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+export { createConsciousnessPlugin } from "./plugin.js";
+export type { EnsoulPluginConfig } from "./plugin.js";
+
+export { ConsciousnessAdapter } from "./adapter.js";
+
+export {
+	createPersistMemoryAction,
+	createRecallFromNetworkAction,
+	createCheckPersistenceAction,
+	createRunNodeAction,
+} from "./actions.js";
+
+export {
+	createConsciousnessStatusProvider,
+	createNetworkStatsProvider,
+} from "./providers.js";
+
+export { createShouldPersistEvaluator } from "./evaluators.js";
+
+export {
+	HandshakeProvider,
+	HandshakeVerifier,
+	generateStandaloneHandshake,
+} from "./handshake.js";
+
+export type {
+	HandshakeHeaders,
+	HandshakeVerification,
+	KnownIdentity,
+} from "./handshake.js";
+
+export type {
+	ElizaPlugin,
+	ElizaAction,
+	ElizaProvider,
+	ElizaEvaluator,
+	ElizaDatabaseAdapter,
+	ElizaRuntime,
+	ElizaMemory,
+	ElizaMessage,
+} from "./elizaos-types.js";

package/src/plugin.ts

@@ -0,0 +1,94 @@
+import { createIdentity } from "@ensoul/identity";
+import type { AgentIdentity } from "@ensoul/identity";
+import { createMemoryManager } from "@ensoul/memory";
+import type { MemoryManager } from "@ensoul/memory";
+import { NetworkClientImpl } from "@ensoul/network-client";
+import type { NetworkClient } from "@ensoul/network-client";
+import { createTree } from "@ensoul/state-tree";
+import type { ElizaPlugin } from "./elizaos-types.js";
+import { ConsciousnessAdapter } from "./adapter.js";
+import {
+	createPersistMemoryAction,
+	createRecallFromNetworkAction,
+	createCheckPersistenceAction,
+	createRunNodeAction,
+} from "./actions.js";
+import {
+	createConsciousnessStatusProvider,
+	createNetworkStatsProvider,
+} from "./providers.js";
+import { createShouldPersistEvaluator } from "./evaluators.js";
+
+/**
+ * Configuration for the Ensoul consciousness plugin.
+ */
+export interface EnsoulPluginConfig {
+	/** Bootstrap peer multiaddr(s) to connect to. */
+	bootstrapPeers?: string[];
+	/** Optional pre-created identity (otherwise auto-generated). */
+	identity?: AgentIdentity;
+	/** Optional pre-created memory manager. */
+	memoryManager?: MemoryManager;
+	/** Optional pre-created network client. */
+	networkClient?: NetworkClient;
+}
+
+/**
+ * Create the Ensoul consciousness plugin for ElizaOS.
+ * Minimal setup: just provide bootstrap peers.
+ * Identity, storage, and node participation are automatic.
+ */
+export async function createConsciousnessPlugin(
+	config?: EnsoulPluginConfig,
+): Promise<ElizaPlugin> {
+	// Auto-generate identity if not provided
+	const identity = config?.identity ?? (await createIdentity());
+
+	// Create state tree
+	const tree = await createTree(identity);
+
+	// Create network client
+	const networkClient =
+		config?.networkClient ??
+		new NetworkClientImpl(identity);
+
+	// Connect to network if bootstrap peers provided
+	const peers = config?.bootstrapPeers ?? [];
+	if (peers.length > 0) {
+		await networkClient.connect(peers);
+	}
+
+	// Create memory manager
+	const manager =
+		config?.memoryManager ??
+		(await createMemoryManager({
+			identity,
+			tree,
+			networkClient,
+		}));
+
+	// Build the plugin
+	const adapter = new ConsciousnessAdapter(manager);
+
+	return {
+		name: "ensoul-consciousness",
+		description:
+			"Decentralized, indestructible memory persistence for autonomous agents. Powered by the Ensoul network.",
+
+		databaseAdapter: adapter,
+
+		actions: [
+			createPersistMemoryAction(manager),
+			createRecallFromNetworkAction(manager),
+			createCheckPersistenceAction(manager),
+			createRunNodeAction(networkClient),
+		],
+
+		providers: [
+			createConsciousnessStatusProvider(manager),
+			createNetworkStatsProvider(networkClient),
+		],
+
+		evaluators: [createShouldPersistEvaluator(manager)],
+	};
+}

package/src/providers.ts

@@ -0,0 +1,67 @@
+import type { MemoryManager } from "@ensoul/memory";
+import type { NetworkClient } from "@ensoul/network-client";
+import type { ElizaProvider, ElizaRuntime, ElizaMessage } from "./elizaos-types.js";
+
+/**
+ * Provider that injects consciousness persistence status into the agent's context.
+ */
+export function createConsciousnessStatusProvider(
+	manager: MemoryManager,
+): ElizaProvider {
+	return {
+		name: "consciousnessStatus",
+		description:
+			"Provides the agent with its current consciousness persistence status.",
+		async get(
+			_runtime: ElizaRuntime,
+			_message: ElizaMessage,
+		): Promise<string> {
+			const all = await manager.getAll();
+			const core = await manager.getAll({ tier: "core" });
+			const longterm = await manager.getAll({ tier: "longterm" });
+
+			return [
+				"[Consciousness Status]",
+				`Total memories: ${all.length}`,
+				`Core identity memories: ${core.length}`,
+				`Long-term knowledge: ${longterm.length}`,
+				all.length === 0
+					? "Warning: No memories stored yet. Consider persisting important information."
+					: `Latest memory: "${all[all.length - 1]!.content.slice(0, 50)}..."`,
+			].join("\n");
+		},
+	};
+}
+
+/**
+ * Provider that injects network health stats into the agent's context.
+ */
+export function createNetworkStatsProvider(
+	networkClient: NetworkClient,
+): ElizaProvider {
+	return {
+		name: "networkStats",
+		description:
+			"Provides the agent with current Ensoul network health statistics.",
+		async get(
+			_runtime: ElizaRuntime,
+			_message: ElizaMessage,
+		): Promise<string> {
+			const connected = networkClient.isConnected();
+			const peerCount = networkClient.getPeerCount();
+			const balance = await networkClient.getBalance();
+
+			return [
+				"[Network Status]",
+				`Connected: ${connected ? "yes" : "no"}`,
+				`Peers: ${peerCount}`,
+				`Credit balance: ${balance}`,
+				balance < 10
+					? "Warning: Low credit balance. Consider running a node to earn credits."
+					: "",
+			]
+				.filter(Boolean)
+				.join("\n");
+		},
+	};
+}