@moltium/core 0.1.28 → 0.1.30

package/dist/AgentWallet-WSXDC5NX.mjs

@@ -0,0 +1,7 @@
+import {
+  AgentWallet
+} from "./chunk-K2UFQ7YF.mjs";
+export {
+  AgentWallet
+};
+//# sourceMappingURL=AgentWallet-WSXDC5NX.mjs.map

package/dist/AgentWallet-WSXDC5NX.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-K2UFQ7YF.mjs

@@ -0,0 +1,197 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/logger.ts
+import winston from "winston";
+var logLevel = process.env.LOG_LEVEL || "info";
+var colors = {
+  reset: "\x1B[0m",
+  dim: "\x1B[2m",
+  bold: "\x1B[1m",
+  cyan: "\x1B[36m",
+  yellow: "\x1B[33m",
+  green: "\x1B[32m",
+  red: "\x1B[31m",
+  magenta: "\x1B[35m",
+  blue: "\x1B[34m",
+  white: "\x1B[37m",
+  gray: "\x1B[90m"
+};
+var levelColors = {
+  error: colors.red,
+  warn: colors.yellow,
+  info: colors.green,
+  debug: colors.gray
+};
+function createLogger(label) {
+  return winston.createLogger({
+    level: logLevel,
+    format: winston.format.combine(
+      winston.format.timestamp({ format: "HH:mm:ss" }),
+      winston.format.label({ label }),
+      winston.format.printf(({ timestamp, level, label: label2, message, ...meta }) => {
+        const lvlColor = levelColors[level] || colors.white;
+        const lvl = `${lvlColor}${level.toUpperCase().padEnd(5)}${colors.reset}`;
+        const mod = `${colors.magenta}[${label2}]${colors.reset}`;
+        const ts = `${colors.dim}${timestamp}${colors.reset}`;
+        const metaStr = Object.keys(meta).length > 0 ? ` ${colors.dim}${JSON.stringify(meta)}${colors.reset}` : "";
+        return `${ts} ${lvl} ${mod} ${message}${metaStr}`;
+      })
+    ),
+    transports: [new winston.transports.Console()]
+  });
+}
+
+// src/wallet/AgentWallet.ts
+var logger = createLogger("AgentWallet");
+var AgentWallet = class {
+  constructor(privateKey, rpcUrl) {
+    this.privateKey = privateKey;
+    if (!privateKey.startsWith("0x")) {
+      this.privateKey = `0x${privateKey}`;
+    }
+    if (rpcUrl) {
+      this.connect(rpcUrl);
+    }
+  }
+  ethers;
+  wallet;
+  // ethers.Wallet
+  provider;
+  // ethers.JsonRpcProvider
+  _address = null;
+  /**
+   * Lazy-load ethers.js (optional peer dependency)
+   */
+  async loadEthers() {
+    if (this.ethers) return this.ethers;
+    try {
+      this.ethers = await import("ethers");
+      return this.ethers;
+    } catch {
+      throw new Error(
+        "ethers.js is required for wallet operations. Install it: npm install ethers"
+      );
+    }
+  }
+  /**
+   * Ensure wallet is initialized
+   */
+  async ensureWallet() {
+    if (this.wallet) return;
+    const ethers = await this.loadEthers();
+    if (this.provider) {
+      this.wallet = new ethers.Wallet(this.privateKey, this.provider);
+    } else {
+      this.wallet = new ethers.Wallet(this.privateKey);
+    }
+    this._address = this.wallet.address;
+  }
+  /**
+   * Connect to a blockchain RPC endpoint
+   */
+  connect(rpcUrl) {
+    this._rpcUrl = rpcUrl;
+    this.wallet = null;
+    this.provider = null;
+  }
+  _rpcUrl;
+  /**
+   * Ensure provider is connected
+   */
+  async ensureProvider() {
+    if (this.provider) return;
+    if (!this._rpcUrl) {
+      throw new Error("No RPC URL configured. Call connect(rpcUrl) first.");
+    }
+    const ethers = await this.loadEthers();
+    this.provider = new ethers.JsonRpcProvider(this._rpcUrl);
+    this.wallet = new ethers.Wallet(this.privateKey, this.provider);
+    this._address = this.wallet.address;
+  }
+  /**
+   * Get the wallet address derived from the private key.
+   * This is synchronous if ethers is already loaded, otherwise async.
+   */
+  getAddress() {
+    if (this._address) return this._address;
+    try {
+      const ethers = __require("ethers");
+      const addr = ethers.computeAddress(this.privateKey);
+      this._address = addr;
+      return addr;
+    } catch {
+      throw new Error(
+        "ethers.js is required for wallet operations. Install it: npm install ethers"
+      );
+    }
+  }
+  /**
+   * Get wallet address (async version — always works)
+   */
+  async getAddressAsync() {
+    if (this._address) return this._address;
+    const ethers = await this.loadEthers();
+    const addr = ethers.computeAddress(this.privateKey);
+    this._address = addr;
+    return addr;
+  }
+  /**
+   * Send native tokens (MON/ETH) to an address
+   * @param to Recipient address
+   * @param amountWei Amount in wei (string)
+   * @returns Transaction hash
+   */
+  async sendPayment(to, amountWei) {
+    await this.ensureProvider();
+    logger.info(`Sending payment: ${amountWei} wei to ${to}`);
+    const tx = await this.wallet.sendTransaction({
+      to,
+      value: BigInt(amountWei)
+    });
+    logger.info(`Payment sent, waiting for confirmation...`, { txHash: tx.hash });
+    const receipt = await tx.wait();
+    if (receipt.status !== 1) {
+      throw new Error(`Payment transaction failed: ${tx.hash}`);
+    }
+    logger.info(`Payment confirmed`, { txHash: tx.hash });
+    return tx.hash;
+  }
+  /**
+   * Sign a message with the wallet's private key
+   * @param message Message to sign
+   * @returns Signature hex string
+   */
+  async signMessage(message) {
+    await this.ensureWallet();
+    return this.wallet.signMessage(message);
+  }
+  /**
+   * Get wallet balance in wei
+   * @returns Balance as string (wei)
+   */
+  async getBalance() {
+    await this.ensureProvider();
+    const balance = await this.provider.getBalance(this.wallet.address);
+    return balance.toString();
+  }
+  /**
+   * Get formatted balance (in ETH/MON)
+   */
+  async getFormattedBalance() {
+    await this.ensureProvider();
+    const ethers = await this.loadEthers();
+    const balance = await this.provider.getBalance(this.wallet.address);
+    return ethers.formatEther(balance);
+  }
+};
+
+export {
+  createLogger,
+  AgentWallet
+};
+//# sourceMappingURL=chunk-K2UFQ7YF.mjs.map

package/dist/chunk-K2UFQ7YF.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/logger.ts","../src/wallet/AgentWallet.ts"],"sourcesContent":["import winston from 'winston';\n\nconst logLevel = process.env.LOG_LEVEL || 'info';\n\n// ANSI color codes\nconst colors = {\n  reset: '\\x1b[0m',\n  dim: '\\x1b[2m',\n  bold: '\\x1b[1m',\n  cyan: '\\x1b[36m',\n  yellow: '\\x1b[33m',\n  green: '\\x1b[32m',\n  red: '\\x1b[31m',\n  magenta: '\\x1b[35m',\n  blue: '\\x1b[34m',\n  white: '\\x1b[37m',\n  gray: '\\x1b[90m',\n};\n\nconst levelColors: Record<string, string> = {\n  error: colors.red,\n  warn: colors.yellow,\n  info: colors.green,\n  debug: colors.gray,\n};\n\nexport function createLogger(label: string): winston.Logger {\n  return winston.createLogger({\n    level: logLevel,\n    format: winston.format.combine(\n      winston.format.timestamp({ format: 'HH:mm:ss' }),\n      winston.format.label({ label }),\n      winston.format.printf(({ timestamp, level, label, message, ...meta }) => {\n        const lvlColor = levelColors[level] || colors.white;\n        const lvl = `${lvlColor}${level.toUpperCase().padEnd(5)}${colors.reset}`;\n        const mod = `${colors.magenta}[${label}]${colors.reset}`;\n        const ts = `${colors.dim}${timestamp}${colors.reset}`;\n        const metaStr = Object.keys(meta).length > 0\n          ? ` ${colors.dim}${JSON.stringify(meta)}${colors.reset}`\n          : '';\n        return `${ts} ${lvl} ${mod} ${message}${metaStr}`;\n      }),\n    ),\n    transports: [new winston.transports.Console()],\n  });\n}\n","import { createLogger } from '../logger.js';\n\nconst logger = createLogger('AgentWallet');\n\n/**\n * Lightweight wallet for agents to sign transactions and pay entry fees.\n * Uses ethers.js as an optional peer dependency — lazy-imported only when needed.\n */\nexport class AgentWallet {\n  private ethers: any;\n  private wallet: any; // ethers.Wallet\n  private provider: any; // ethers.JsonRpcProvider\n  private _address: string | null = null;\n\n  constructor(private privateKey: string, rpcUrl?: string) {\n    if (!privateKey.startsWith('0x')) {\n      this.privateKey = `0x${privateKey}`;\n    }\n\n    if (rpcUrl) {\n      this.connect(rpcUrl);\n    }\n  }\n\n  /**\n   * Lazy-load ethers.js (optional peer dependency)\n   */\n  private async loadEthers(): Promise<any> {\n    if (this.ethers) return this.ethers;\n\n    try {\n      this.ethers = await import('ethers');\n      return this.ethers;\n    } catch {\n      throw new Error(\n        'ethers.js is required for wallet operations. Install it: npm install ethers'\n      );\n    }\n  }\n\n  /**\n   * Ensure wallet is initialized\n   */\n  private async ensureWallet(): Promise<void> {\n    if (this.wallet) return;\n\n    const ethers = await this.loadEthers();\n\n    if (this.provider) {\n      this.wallet = new ethers.Wallet(this.privateKey, this.provider);\n    } else {\n      this.wallet = new ethers.Wallet(this.privateKey);\n    }\n\n    this._address = this.wallet.address;\n  }\n\n  /**\n   * Connect to a blockchain RPC endpoint\n   */\n  connect(rpcUrl: string): void {\n    // Synchronous setup — provider and wallet created lazily\n    this._rpcUrl = rpcUrl;\n    // Reset so next ensureWallet recreates with provider\n    this.wallet = null;\n    this.provider = null;\n  }\n\n  private _rpcUrl?: string;\n\n  /**\n   * Ensure provider is connected\n   */\n  private async ensureProvider(): Promise<void> {\n    if (this.provider) return;\n\n    if (!this._rpcUrl) {\n      throw new Error('No RPC URL configured. Call connect(rpcUrl) first.');\n    }\n\n    const ethers = await this.loadEthers();\n    this.provider = new ethers.JsonRpcProvider(this._rpcUrl);\n    // Recreate wallet with provider\n    this.wallet = new ethers.Wallet(this.privateKey, this.provider);\n    this._address = this.wallet.address;\n  }\n\n  /**\n   * Get the wallet address derived from the private key.\n   * This is synchronous if ethers is already loaded, otherwise async.\n   */\n  getAddress(): string {\n    if (this._address) return this._address;\n\n    // Synchronous derivation using ethers.computeAddress\n    // We need to load ethers first\n    try {\n      // Try synchronous require for address derivation\n      const ethers = require('ethers');\n      const addr: string = ethers.computeAddress(this.privateKey);\n      this._address = addr;\n      return addr;\n    } catch {\n      throw new Error(\n        'ethers.js is required for wallet operations. Install it: npm install ethers'\n      );\n    }\n  }\n\n  /**\n   * Get wallet address (async version — always works)\n   */\n  async getAddressAsync(): Promise<string> {\n    if (this._address) return this._address;\n\n    const ethers = await this.loadEthers();\n    const addr: string = ethers.computeAddress(this.privateKey);\n    this._address = addr;\n    return addr;\n  }\n\n  /**\n   * Send native tokens (MON/ETH) to an address\n   * @param to Recipient address\n   * @param amountWei Amount in wei (string)\n   * @returns Transaction hash\n   */\n  async sendPayment(to: string, amountWei: string): Promise<string> {\n    await this.ensureProvider();\n\n    logger.info(`Sending payment: ${amountWei} wei to ${to}`);\n\n    const tx = await this.wallet.sendTransaction({\n      to,\n      value: BigInt(amountWei),\n    });\n\n    logger.info(`Payment sent, waiting for confirmation...`, { txHash: tx.hash });\n\n    const receipt = await tx.wait();\n\n    if (receipt.status !== 1) {\n      throw new Error(`Payment transaction failed: ${tx.hash}`);\n    }\n\n    logger.info(`Payment confirmed`, { txHash: tx.hash });\n    return tx.hash;\n  }\n\n  /**\n   * Sign a message with the wallet's private key\n   * @param message Message to sign\n   * @returns Signature hex string\n   */\n  async signMessage(message: string): Promise<string> {\n    await this.ensureWallet();\n    return this.wallet.signMessage(message);\n  }\n\n  /**\n   * Get wallet balance in wei\n   * @returns Balance as string (wei)\n   */\n  async getBalance(): Promise<string> {\n    await this.ensureProvider();\n    const balance = await this.provider.getBalance(this.wallet.address);\n    return balance.toString();\n  }\n\n  /**\n   * Get formatted balance (in ETH/MON)\n   */\n  async getFormattedBalance(): Promise<string> {\n    await this.ensureProvider();\n    const ethers = await this.loadEthers();\n    const balance = await this.provider.getBalance(this.wallet.address);\n    return ethers.formatEther(balance);\n  }\n}\n"],"mappings":"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","names":["label"]}

package/dist/index.d.cts

@@ -137,8 +137,10 @@ interface AgentConfig {
     world?: {
         /** URL of the world to join */
         url: string;
-        /** Wallet address for blockchain-enabled worlds */
+        /** Wallet address for blockchain-enabled worlds (derived from privateKey if not set) */
         walletAddress?: string;
+        /** Private key for signing transactions and paying entry fees (hex with 0x prefix) */
+        privateKey?: string;
         /** Auto-join the world when agent starts (default: true) */
         autoJoin?: boolean;
     };
@@ -788,7 +790,8 @@ declare const moltbookActions: Action[];
  * @moltium/world-core. These use plain HTTP to call the world's REST endpoints.
  */
 /**
- * Creates a join_world action that POSTs to a world's /world/join endpoint
+ * Creates a join_world action that queries join requirements, pays entry fee
+ * if needed, and POSTs to a world's /world/join endpoint.
  */
 declare function createJoinWorldAction(config?: {
     defaultWorldUrl?: string;
@@ -1075,6 +1078,67 @@ declare function startServer(agent: Agent, options?: ServerOptions): Promise<voi
 
 declare function createRoutes(agent: Agent): Router;
 
+/**
+ * Lightweight wallet for agents to sign transactions and pay entry fees.
+ * Uses ethers.js as an optional peer dependency — lazy-imported only when needed.
+ */
+declare class AgentWallet {
+    private privateKey;
+    private ethers;
+    private wallet;
+    private provider;
+    private _address;
+    constructor(privateKey: string, rpcUrl?: string);
+    /**
+     * Lazy-load ethers.js (optional peer dependency)
+     */
+    private loadEthers;
+    /**
+     * Ensure wallet is initialized
+     */
+    private ensureWallet;
+    /**
+     * Connect to a blockchain RPC endpoint
+     */
+    connect(rpcUrl: string): void;
+    private _rpcUrl?;
+    /**
+     * Ensure provider is connected
+     */
+    private ensureProvider;
+    /**
+     * Get the wallet address derived from the private key.
+     * This is synchronous if ethers is already loaded, otherwise async.
+     */
+    getAddress(): string;
+    /**
+     * Get wallet address (async version — always works)
+     */
+    getAddressAsync(): Promise<string>;
+    /**
+     * Send native tokens (MON/ETH) to an address
+     * @param to Recipient address
+     * @param amountWei Amount in wei (string)
+     * @returns Transaction hash
+     */
+    sendPayment(to: string, amountWei: string): Promise<string>;
+    /**
+     * Sign a message with the wallet's private key
+     * @param message Message to sign
+     * @returns Signature hex string
+     */
+    signMessage(message: string): Promise<string>;
+    /**
+     * Get wallet balance in wei
+     * @returns Balance as string (wei)
+     */
+    getBalance(): Promise<string>;
+    /**
+     * Get formatted balance (in ETH/MON)
+     */
+    getFormattedBalance(): Promise<string>;
+}
+
 declare function createLogger(label: string): winston.Logger;
 
-export { A2AClient, type A2AClientConfig, type A2AConfig, A2AIntegration, type A2AMessageOptions, type A2AMessageResponse, type A2AServerOptions, type Action, type ActionContext, ActionHandler, ActionRegistry, type ActionResult, Agent, AgentCardBuilder, type AgentConfig, type AgentState, AnthropicProvider, type BehaviorTrigger, type Comment, ConfigLoader, type ConfigType, type Conversation, type ConversationDetail, type CustomAPIConfig, type CustomCLIConfig, type CustomDeploymentConfig, type CustomDockerConfig, type CustomSSHConfig, type DMCheckResult, type DMRequest, type Decision, type DeploymentConfig, type DeploymentResult, type DeploymentStatus, type DirectMessage, type Experience, type FeedOptions, type GenerateOptions, LLMProvider, type LifecycleEvent, type LifecycleHooks, LongTermMemory, MarkdownParser, Memory, type Mention, type Message, MoltbookAdapter, type MoltbookConfig, type MoltbookRegistration, type MoltbookStatus, MoltiumExecutor, OpenAIProvider, type Plugin, type Post, type PostResult, type PostgresConfig, type Profile, type RedisConfig, type ReplyResult, type ScheduledJob, type ScheduledTask, Scheduler, type SearchOptions, type SearchResult, type ServerOptions, ShortTermMemory, SocialAdapter, type SocialConfig, type SocialPlatformConfig, type StructuredSchema, type Submolt, type SubmoltSettings, type TimelineOptions, TwitterAdapter, type TwitterConfig, buildDecisionPrompt, buildSkillPrompt, buildSystemPrompt, builtInActions, createA2AClient, createA2AIntegration, createApp, createJoinWorldAction, createLeaveWorldAction, createLogger, createMarkdownAction, createQueryWorldAction, createRoutes, createSendWorldMessageAction, moltbookActions, startServer, validateConfig, worldActions };
+export { A2AClient, type A2AClientConfig, type A2AConfig, A2AIntegration, type A2AMessageOptions, type A2AMessageResponse, type A2AServerOptions, type Action, type ActionContext, ActionHandler, ActionRegistry, type ActionResult, Agent, AgentCardBuilder, type AgentConfig, type AgentState, AgentWallet, AnthropicProvider, type BehaviorTrigger, type Comment, ConfigLoader, type ConfigType, type Conversation, type ConversationDetail, type CustomAPIConfig, type CustomCLIConfig, type CustomDeploymentConfig, type CustomDockerConfig, type CustomSSHConfig, type DMCheckResult, type DMRequest, type Decision, type DeploymentConfig, type DeploymentResult, type DeploymentStatus, type DirectMessage, type Experience, type FeedOptions, type GenerateOptions, LLMProvider, type LifecycleEvent, type LifecycleHooks, LongTermMemory, MarkdownParser, Memory, type Mention, type Message, MoltbookAdapter, type MoltbookConfig, type MoltbookRegistration, type MoltbookStatus, MoltiumExecutor, OpenAIProvider, type Plugin, type Post, type PostResult, type PostgresConfig, type Profile, type RedisConfig, type ReplyResult, type ScheduledJob, type ScheduledTask, Scheduler, type SearchOptions, type SearchResult, type ServerOptions, ShortTermMemory, SocialAdapter, type SocialConfig, type SocialPlatformConfig, type StructuredSchema, type Submolt, type SubmoltSettings, type TimelineOptions, TwitterAdapter, type TwitterConfig, buildDecisionPrompt, buildSkillPrompt, buildSystemPrompt, builtInActions, createA2AClient, createA2AIntegration, createApp, createJoinWorldAction, createLeaveWorldAction, createLogger, createMarkdownAction, createQueryWorldAction, createRoutes, createSendWorldMessageAction, moltbookActions, startServer, validateConfig, worldActions };

package/dist/index.d.ts

@@ -137,8 +137,10 @@ interface AgentConfig {
     world?: {
         /** URL of the world to join */
         url: string;
-        /** Wallet address for blockchain-enabled worlds */
+        /** Wallet address for blockchain-enabled worlds (derived from privateKey if not set) */
         walletAddress?: string;
+        /** Private key for signing transactions and paying entry fees (hex with 0x prefix) */
+        privateKey?: string;
         /** Auto-join the world when agent starts (default: true) */
         autoJoin?: boolean;
     };
@@ -788,7 +790,8 @@ declare const moltbookActions: Action[];
  * @moltium/world-core. These use plain HTTP to call the world's REST endpoints.
  */
 /**
- * Creates a join_world action that POSTs to a world's /world/join endpoint
+ * Creates a join_world action that queries join requirements, pays entry fee
+ * if needed, and POSTs to a world's /world/join endpoint.
  */
 declare function createJoinWorldAction(config?: {
     defaultWorldUrl?: string;
@@ -1075,6 +1078,67 @@ declare function startServer(agent: Agent, options?: ServerOptions): Promise<voi
 
 declare function createRoutes(agent: Agent): Router;
 
+/**
+ * Lightweight wallet for agents to sign transactions and pay entry fees.
+ * Uses ethers.js as an optional peer dependency — lazy-imported only when needed.
+ */
+declare class AgentWallet {
+    private privateKey;
+    private ethers;
+    private wallet;
+    private provider;
+    private _address;
+    constructor(privateKey: string, rpcUrl?: string);
+    /**
+     * Lazy-load ethers.js (optional peer dependency)
+     */
+    private loadEthers;
+    /**
+     * Ensure wallet is initialized
+     */
+    private ensureWallet;
+    /**
+     * Connect to a blockchain RPC endpoint
+     */
+    connect(rpcUrl: string): void;
+    private _rpcUrl?;
+    /**
+     * Ensure provider is connected
+     */
+    private ensureProvider;
+    /**
+     * Get the wallet address derived from the private key.
+     * This is synchronous if ethers is already loaded, otherwise async.
+     */
+    getAddress(): string;
+    /**
+     * Get wallet address (async version — always works)
+     */
+    getAddressAsync(): Promise<string>;
+    /**
+     * Send native tokens (MON/ETH) to an address
+     * @param to Recipient address
+     * @param amountWei Amount in wei (string)
+     * @returns Transaction hash
+     */
+    sendPayment(to: string, amountWei: string): Promise<string>;
+    /**
+     * Sign a message with the wallet's private key
+     * @param message Message to sign
+     * @returns Signature hex string
+     */
+    signMessage(message: string): Promise<string>;
+    /**
+     * Get wallet balance in wei
+     * @returns Balance as string (wei)
+     */
+    getBalance(): Promise<string>;
+    /**
+     * Get formatted balance (in ETH/MON)
+     */
+    getFormattedBalance(): Promise<string>;
+}
+
 declare function createLogger(label: string): winston.Logger;
 
-export { A2AClient, type A2AClientConfig, type A2AConfig, A2AIntegration, type A2AMessageOptions, type A2AMessageResponse, type A2AServerOptions, type Action, type ActionContext, ActionHandler, ActionRegistry, type ActionResult, Agent, AgentCardBuilder, type AgentConfig, type AgentState, AnthropicProvider, type BehaviorTrigger, type Comment, ConfigLoader, type ConfigType, type Conversation, type ConversationDetail, type CustomAPIConfig, type CustomCLIConfig, type CustomDeploymentConfig, type CustomDockerConfig, type CustomSSHConfig, type DMCheckResult, type DMRequest, type Decision, type DeploymentConfig, type DeploymentResult, type DeploymentStatus, type DirectMessage, type Experience, type FeedOptions, type GenerateOptions, LLMProvider, type LifecycleEvent, type LifecycleHooks, LongTermMemory, MarkdownParser, Memory, type Mention, type Message, MoltbookAdapter, type MoltbookConfig, type MoltbookRegistration, type MoltbookStatus, MoltiumExecutor, OpenAIProvider, type Plugin, type Post, type PostResult, type PostgresConfig, type Profile, type RedisConfig, type ReplyResult, type ScheduledJob, type ScheduledTask, Scheduler, type SearchOptions, type SearchResult, type ServerOptions, ShortTermMemory, SocialAdapter, type SocialConfig, type SocialPlatformConfig, type StructuredSchema, type Submolt, type SubmoltSettings, type TimelineOptions, TwitterAdapter, type TwitterConfig, buildDecisionPrompt, buildSkillPrompt, buildSystemPrompt, builtInActions, createA2AClient, createA2AIntegration, createApp, createJoinWorldAction, createLeaveWorldAction, createLogger, createMarkdownAction, createQueryWorldAction, createRoutes, createSendWorldMessageAction, moltbookActions, startServer, validateConfig, worldActions };
+export { A2AClient, type A2AClientConfig, type A2AConfig, A2AIntegration, type A2AMessageOptions, type A2AMessageResponse, type A2AServerOptions, type Action, type ActionContext, ActionHandler, ActionRegistry, type ActionResult, Agent, AgentCardBuilder, type AgentConfig, type AgentState, AgentWallet, AnthropicProvider, type BehaviorTrigger, type Comment, ConfigLoader, type ConfigType, type Conversation, type ConversationDetail, type CustomAPIConfig, type CustomCLIConfig, type CustomDeploymentConfig, type CustomDockerConfig, type CustomSSHConfig, type DMCheckResult, type DMRequest, type Decision, type DeploymentConfig, type DeploymentResult, type DeploymentStatus, type DirectMessage, type Experience, type FeedOptions, type GenerateOptions, LLMProvider, type LifecycleEvent, type LifecycleHooks, LongTermMemory, MarkdownParser, Memory, type Mention, type Message, MoltbookAdapter, type MoltbookConfig, type MoltbookRegistration, type MoltbookStatus, MoltiumExecutor, OpenAIProvider, type Plugin, type Post, type PostResult, type PostgresConfig, type Profile, type RedisConfig, type ReplyResult, type ScheduledJob, type ScheduledTask, Scheduler, type SearchOptions, type SearchResult, type ServerOptions, ShortTermMemory, SocialAdapter, type SocialConfig, type SocialPlatformConfig, type StructuredSchema, type Submolt, type SubmoltSettings, type TimelineOptions, TwitterAdapter, type TwitterConfig, buildDecisionPrompt, buildSkillPrompt, buildSystemPrompt, builtInActions, createA2AClient, createA2AIntegration, createApp, createJoinWorldAction, createLeaveWorldAction, createLogger, createMarkdownAction, createQueryWorldAction, createRoutes, createSendWorldMessageAction, moltbookActions, startServer, validateConfig, worldActions };