@hashgraphonline/conversational-agent 0.1.213 → 0.1.214

package/cli/readme.md

@@ -0,0 +1,181 @@
+# Hedera Conversational Agent CLI
+
+A beautiful command-line interface for the Hedera Conversational Agent, built with [Ink](https://github.com/vadimdemedes/ink) and styled following Hashgraph Online design patterns.
+
+## Features
+
+- 🎨 **Beautiful Terminal UI** - Styled with HCS improvement proposals design patterns
+- 💬 **Interactive Chat** - Chat with your Hedera agent in a clean terminal interface
+- 🔐 **Secure Configuration** - Masked input for sensitive credentials
+- 🌈 **Gradient Text & Colors** - Brand-consistent color scheme
+- 🚀 **Fast & Responsive** - Built with React for smooth interactions
+- 📊 **Transaction Details** - See transaction IDs and network responses
+- 🎯 **HCS-10 Support** - Full support for agent connections and messaging
+- 🔧 **MCP Integration** - Configure Model Context Protocol servers for extended capabilities
+- 📁 **File Operations** - Built-in filesystem MCP server for file management
+- ⚙️ **Custom MCP Servers** - Add your own MCP servers for specialized tools
+
+## Installation
+
+For local development, the CLI uses the actual ConversationalAgent from the parent package:
+
+```bash
+# 1. Build the parent package first
+cd /path/to/conversational-agent
+pnpm install
+pnpm build
+
+# 2. The CLI will be built automatically via postinstall hook
+# Or build manually:
+cd cli
+pnpm install
+pnpm build
+```
+
+## Usage
+
+### Interactive Mode (Recommended)
+
+```bash
+# From the parent conversational-agent directory
+pnpm cli
+
+# This automatically builds if needed and runs the CLI
+```
+
+### With Command Line Arguments
+
+```bash
+conversational-agent \
+  --account-id=0.0.12345 \
+  --private-key=your-private-key \
+  --network=testnet \
+  --openai-api-key=sk-...
+```
+
+### Using Environment Variables
+
+The CLI automatically loads configuration from `.env` in the conversational-agent root:
+
+```bash
+# .env file in conversational-agent directory
+HEDERA_ACCOUNT_ID=0.0.12345
+HEDERA_PRIVATE_KEY=your-private-key
+HEDERA_NETWORK=testnet
+OPENAI_API_KEY=sk-...
+MCP_SERVERS=[{"name":"filesystem","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/tmp"]}]
+```
+
+Then simply run: `pnpm cli`
+
+## Interface Overview
+
+### Welcome Screen
+- Beautiful ASCII art logo with gradient colors
+- Simple menu navigation with arrow keys
+- Options: Start Chat, Configure, MCP Servers, Exit
+
+### Configuration Screen
+- Terminal-style window with macOS-like controls
+- Secure input masking for sensitive data
+- Tab navigation between fields
+- Real-time validation
+
+### MCP Servers Screen
+- Configure Model Context Protocol servers
+- Enable/disable filesystem server with custom path
+- Add custom MCP servers with command and arguments
+- Live preview of available tools
+- Save configuration to environment
+
+### Chat Interface
+- Clean terminal aesthetic with prompt symbols
+- Color-coded messages (user, assistant, system)
+- Loading indicators with spinners
+- Transaction ID display
+- MCP server status and available tools
+- Escape key to return to menu
+
+## Design Features
+
+The CLI follows Hashgraph Online's design system:
+
+- **Brand Colors**: Primary blue (#5599fe), Green (#48df7b), Purple (#b56cff)
+- **Hedera Colors**: Purple (#8259ef), Blue (#2d84eb), Green (#3ec878)
+- **Terminal Window**: Rounded borders with window control dots
+- **Status Badges**: Color-coded status indicators
+- **Typography**: Monospace throughout with clear hierarchy
+
+## Keyboard Shortcuts
+
+- `↑/↓` - Navigate menus
+- `Enter` - Select/Submit
+- `Tab` - Next field (in configuration)
+- `Escape` - Return to main menu (from chat)
+- `Ctrl+C` - Exit application
+
+## Development
+
+```bash
+# Watch mode for development
+pnpm dev
+
+# Run tests
+pnpm test
+
+# Build for production
+pnpm build
+```
+
+## Examples
+
+### Basic Chat Interaction
+
+```
+$ Find all AI agents on the network
+→ I'll search for AI agents registered on the Hedera network...
+
+[INFO] Found 5 agents with AI capabilities
+→ Here are the AI agents I found:
+1. Agent: 0.0.12345 - "GPT Assistant"
+2. Agent: 0.0.23456 - "Code Helper"
+...
+
+$ Connect to agent 0.0.12345
+→ Initiating connection to agent 0.0.12345...
+[INFO] Transaction ID: 0.0.98765@1234567890.123
+→ Successfully connected! You can now send messages to this agent.
+```
+
+### MCP File Operations
+
+With filesystem MCP server enabled:
+
+```
+$ Create a new file called notes.txt with my meeting notes
+→ I'll create a notes.txt file for you with meeting notes...
+
+[INFO] MCP servers enabled: filesystem
+→ I've created notes.txt in your configured directory with the meeting notes.
+
+$ List all files in the current directory
+→ Here are the files in /tmp:
+- notes.txt (created just now)
+- data.json
+- config.yaml
+```
+
+### Custom MCP Server
+
+```
+$ Add GitHub repository operations
+→ I can help you interact with GitHub repositories...
+
+[INFO] MCP servers enabled: filesystem, github
+→ I now have access to GitHub operations. I can help you create issues, 
+  manage repositories, and work with pull requests.
+```
+
+## License
+
+Apache-2.0

package/dist/esm/index14.js

@@ -1,5 +1,5 @@
-import { ReferenceIdGenerator } from "./index24.js";
-import { DEFAULT_CONTENT_REFERENCE_CONFIG, ContentReferenceError } from "./index25.js";
+import { ReferenceIdGenerator } from "./index25.js";
+import { DEFAULT_CONTENT_REFERENCE_CONFIG, ContentReferenceError } from "./index26.js";
 const _ContentStorage = class _ContentStorage {
   constructor(maxStorage = _ContentStorage.DEFAULT_MAX_STORAGE, referenceConfig) {
     this.messages = [];

package/dist/esm/index18.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { AccountBuilder } from "./index26.js";
+import { AccountBuilder } from "./index24.js";
 import { BaseHederaTransactionTool } from "hedera-agent-kit";
 const HbarTransferInputSchema = z.object({
   accountId: z.string().describe('Account ID for the transfer (e.g., "0.0.xxxx").'),

package/dist/esm/index24.js

@@ -1,68 +1,95 @@
-import { createHash } from "crypto";
-class ReferenceIdGenerator {
-  /**
-   * Generate a content-based reference ID using SHA-256 hashing
-   * 
-   * @param content The content to generate a reference ID for
-   * @returns Deterministic reference ID based on content hash
-   */
-  static generateId(content) {
-    const hash = createHash("sha256");
-    hash.update(content);
-    return hash.digest("hex");
+import { TransferTransaction, AccountId, Hbar } from "@hashgraph/sdk";
+import BigNumber from "bignumber.js";
+import { BaseServiceBuilder } from "hedera-agent-kit";
+class AccountBuilder extends BaseServiceBuilder {
+  constructor(hederaKit) {
+    super(hederaKit);
   }
   /**
-   * Validate that a string is a properly formatted reference ID
-   * 
-   * @param id The ID to validate
-   * @returns true if the ID is valid format
+   * Transfers HBAR between accounts with proper decimal handling
    */
-  static isValidReferenceId(id) {
-    if (!id || typeof id !== "string") {
-      return false;
+  transferHbar(params, isUserInitiated = true) {
+    this.clearNotes();
+    const transaction = new TransferTransaction();
+    if (!params.transfers || params.transfers.length === 0) {
+      throw new Error("HbarTransferParams must include at least one transfer.");
     }
-    if (id.length !== 64) {
-      return false;
+    let netZeroInTinybars = new BigNumber(0);
+    let userTransferProcessedForScheduling = false;
+    if (isUserInitiated && this.kit.userAccountId && this.kit.operationalMode === "provideBytes" && params.transfers.length === 1) {
+      const receiverTransfer = params.transfers[0];
+      const amountValue = typeof receiverTransfer.amount === "string" || typeof receiverTransfer.amount === "number" ? receiverTransfer.amount : receiverTransfer.amount.toString();
+      const amountBigNum = new BigNumber(amountValue);
+      if (amountBigNum.isPositive()) {
+        const recipientAccountId = typeof receiverTransfer.accountId === "string" ? AccountId.fromString(receiverTransfer.accountId) : receiverTransfer.accountId;
+        const roundedAmount = amountBigNum.toFixed(8, BigNumber.ROUND_DOWN);
+        const sdkHbarAmount = Hbar.fromString(roundedAmount);
+        this.logger.info(
+          `[AccountBuilder.transferHbar] Configuring user-initiated scheduled transfer: ${sdkHbarAmount.toString()} from ${this.kit.userAccountId} to ${recipientAccountId.toString()}`
+        );
+        this.addNote(
+          `Configured HBAR transfer from your account (${this.kit.userAccountId}) to ${recipientAccountId.toString()} for ${sdkHbarAmount.toString()}.`
+        );
+        transaction.addHbarTransfer(recipientAccountId, sdkHbarAmount);
+        transaction.addHbarTransfer(
+          AccountId.fromString(this.kit.userAccountId),
+          sdkHbarAmount.negated()
+        );
+        userTransferProcessedForScheduling = true;
+      }
     }
-    return /^[a-f0-9]+$/.test(id);
-  }
-  /**
-   * Extract reference ID from ref:// format
-   * 
-   * @param input Input string that may contain a reference ID
-   * @returns Extracted reference ID or null if not found
-   */
-  static extractReferenceId(input) {
-    if (!input || typeof input !== "string") {
-      return null;
+    if (!userTransferProcessedForScheduling) {
+      const processedTransfers = [];
+      for (const transferInput of params.transfers) {
+        const accountId = typeof transferInput.accountId === "string" ? AccountId.fromString(transferInput.accountId) : transferInput.accountId;
+        const amountValue = typeof transferInput.amount === "string" || typeof transferInput.amount === "number" ? transferInput.amount : transferInput.amount.toString();
+        const amountBigNum = new BigNumber(amountValue);
+        const roundedAmount = amountBigNum.toFixed(8, BigNumber.ROUND_DOWN);
+        this.logger.info(
+          `Processing transfer: ${amountValue} HBAR (rounded to ${roundedAmount}) for account ${accountId.toString()}`
+        );
+        const sdkHbarAmount = Hbar.fromString(roundedAmount);
+        processedTransfers.push({
+          accountId,
+          amount: amountBigNum,
+          hbar: sdkHbarAmount
+        });
+        const tinybarsContribution = sdkHbarAmount.toTinybars();
+        netZeroInTinybars = netZeroInTinybars.plus(
+          tinybarsContribution.toString()
+        );
+      }
+      if (!netZeroInTinybars.isZero()) {
+        this.logger.warn(
+          `Transfer sum not zero: ${netZeroInTinybars.toString()} tinybars off. Adjusting last transfer.`
+        );
+        if (processedTransfers.length > 0) {
+          const lastTransfer = processedTransfers[processedTransfers.length - 1];
+          const adjustment = netZeroInTinybars.dividedBy(-1e8);
+          const adjustedAmount = lastTransfer.amount.plus(adjustment);
+          const adjustedRounded = adjustedAmount.toFixed(8, BigNumber.ROUND_DOWN);
+          lastTransfer.hbar = Hbar.fromString(adjustedRounded);
+          this.logger.info(
+            `Adjusted last transfer for ${lastTransfer.accountId.toString()} to ${adjustedRounded} HBAR`
+          );
+        }
+      }
+      for (const transfer of processedTransfers) {
+        transaction.addHbarTransfer(transfer.accountId, transfer.hbar);
+      }
     }
-    const refFormatMatch = input.match(/^ref:\/\/([a-f0-9]{64})$/);
-    if (refFormatMatch) {
-      return refFormatMatch[1];
+    if (typeof params.memo !== "undefined") {
+      if (params.memo === null) {
+        this.logger.warn("Received null for memo in transferHbar.");
+      } else {
+        transaction.setTransactionMemo(params.memo);
+      }
     }
-    return this.isValidReferenceId(input) ? input : null;
-  }
-  /**
-   * Format a reference ID in the standard ref:// format
-   * 
-   * @param referenceId The reference ID to format
-   * @returns Formatted reference string
-   */
-  static formatReference(referenceId) {
-    return `ref://${referenceId}`;
-  }
-  /**
-   * Generate a test reference ID (for testing purposes only)
-   * 
-   * @param testSeed A test seed to generate a fake but valid ID format
-   * @returns A valid format reference ID for testing
-   */
-  static generateTestId(testSeed) {
-    const content = Buffer.from(`test-${testSeed}-${Date.now()}`);
-    return this.generateId(content);
+    this.setCurrentTransaction(transaction);
+    return this;
   }
 }
 export {
-  ReferenceIdGenerator
+  AccountBuilder
 };
 //# sourceMappingURL=index24.js.map

package/dist/esm/index24.js.map

@@ -1 +1 @@
-{"version":3,"file":"index24.js","sources":["../../src/memory/ReferenceIdGenerator.ts"],"sourcesContent":["import { createHash } from 'crypto';\nimport { ReferenceId } from '../types/content-reference';\n\n/**\n * Content-based reference ID generator using SHA-256 (HCS-1 style)\n * \n * Generates deterministic reference IDs based on content hashing.\n * Same content always produces the same reference ID.\n */\nexport class ReferenceIdGenerator {\n  /**\n   * Generate a content-based reference ID using SHA-256 hashing\n   * \n   * @param content The content to generate a reference ID for\n   * @returns Deterministic reference ID based on content hash\n   */\n  static generateId(content: Buffer): ReferenceId {\n    const hash = createHash('sha256');\n    hash.update(content);\n    return hash.digest('hex');\n  }\n  \n  /**\n   * Validate that a string is a properly formatted reference ID\n   * \n   * @param id The ID to validate\n   * @returns true if the ID is valid format\n   */\n  static isValidReferenceId(id: string): id is ReferenceId {\n    if (!id || typeof id !== 'string') {\n      return false;\n    }\n    \n    if (id.length !== 64) {\n      return false;\n    }\n    \n    return /^[a-f0-9]+$/.test(id);\n  }\n  \n  /**\n   * Extract reference ID from ref:// format\n   * \n   * @param input Input string that may contain a reference ID\n   * @returns Extracted reference ID or null if not found\n   */\n  static extractReferenceId(input: string): ReferenceId | null {\n    if (!input || typeof input !== 'string') {\n      return null;\n    }\n    \n    const refFormatMatch = input.match(/^ref:\\/\\/([a-f0-9]{64})$/);\n    if (refFormatMatch) {\n      return refFormatMatch[1] as ReferenceId;\n    }\n    \n    return this.isValidReferenceId(input) ? input : null;\n  }\n  \n  /**\n   * Format a reference ID in the standard ref:// format\n   * \n   * @param referenceId The reference ID to format\n   * @returns Formatted reference string\n   */\n  static formatReference(referenceId: ReferenceId): string {\n    return `ref://${referenceId}`;\n  }\n  \n  /**\n   * Generate a test reference ID (for testing purposes only)\n   * \n   * @param testSeed A test seed to generate a fake but valid ID format\n   * @returns A valid format reference ID for testing\n   */\n  static generateTestId(testSeed: string): ReferenceId {\n    const content = Buffer.from(`test-${testSeed}-${Date.now()}`);\n    return this.generateId(content);\n  }\n}"],"names":[],"mappings":";AASO,MAAM,qBAAqB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOhC,OAAO,WAAW,SAA8B;AAC9C,UAAM,OAAO,WAAW,QAAQ;AAChC,SAAK,OAAO,OAAO;AACnB,WAAO,KAAK,OAAO,KAAK;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAO,mBAAmB,IAA+B;AACvD,QAAI,CAAC,MAAM,OAAO,OAAO,UAAU;AACjC,aAAO;AAAA,IACT;AAEA,QAAI,GAAG,WAAW,IAAI;AACpB,aAAO;AAAA,IACT;AAEA,WAAO,cAAc,KAAK,EAAE;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAO,mBAAmB,OAAmC;AAC3D,QAAI,CAAC,SAAS,OAAO,UAAU,UAAU;AACvC,aAAO;AAAA,IACT;AAEA,UAAM,iBAAiB,MAAM,MAAM,0BAA0B;AAC7D,QAAI,gBAAgB;AAClB,aAAO,eAAe,CAAC;AAAA,IACzB;AAEA,WAAO,KAAK,mBAAmB,KAAK,IAAI,QAAQ;AAAA,EAClD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAO,gBAAgB,aAAkC;AACvD,WAAO,SAAS,WAAW;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAO,eAAe,UAA+B;AACnD,UAAM,UAAU,OAAO,KAAK,QAAQ,QAAQ,IAAI,KAAK,IAAA,CAAK,EAAE;AAC5D,WAAO,KAAK,WAAW,OAAO;AAAA,EAChC;AACF;"}
+{"version":3,"file":"index24.js","sources":["../../src/plugins/hbar/AccountBuilder.ts"],"sourcesContent":["import {\n  AccountId,\n  Hbar,\n  TransferTransaction,\n} from '@hashgraph/sdk';\nimport BigNumber from 'bignumber.js';\nimport { HederaAgentKit, BaseServiceBuilder } from 'hedera-agent-kit';\nimport { HbarTransferParams } from './types';\n\n/**\n * Custom AccountBuilder that properly handles HBAR decimal conversion\n */\nexport class AccountBuilder extends BaseServiceBuilder {\n  constructor(hederaKit: HederaAgentKit) {\n    super(hederaKit);\n  }\n\n  /**\n   * Transfers HBAR between accounts with proper decimal handling\n   */\n  public transferHbar(\n    params: HbarTransferParams,\n    isUserInitiated: boolean = true\n  ): this {\n    this.clearNotes();\n    const transaction = new TransferTransaction();\n    \n    if (!params.transfers || params.transfers.length === 0) {\n      throw new Error('HbarTransferParams must include at least one transfer.');\n    }\n\n    let netZeroInTinybars = new BigNumber(0);\n    let userTransferProcessedForScheduling = false;\n\n    if (\n      isUserInitiated &&\n      this.kit.userAccountId &&\n      (this.kit.operationalMode as string) === 'provideBytes' &&\n      params.transfers.length === 1\n    ) {\n      const receiverTransfer = params.transfers[0];\n      const amountValue =\n        typeof receiverTransfer.amount === 'string' ||\n        typeof receiverTransfer.amount === 'number'\n          ? receiverTransfer.amount\n          : receiverTransfer.amount.toString();\n\n      const amountBigNum = new BigNumber(amountValue);\n\n      if (amountBigNum.isPositive()) {\n        const recipientAccountId =\n          typeof receiverTransfer.accountId === 'string'\n            ? AccountId.fromString(receiverTransfer.accountId)\n            : receiverTransfer.accountId;\n\n        const roundedAmount = amountBigNum.toFixed(8, BigNumber.ROUND_DOWN);\n        const sdkHbarAmount = Hbar.fromString(roundedAmount);\n\n        this.logger.info(\n          `[AccountBuilder.transferHbar] Configuring user-initiated scheduled transfer: ${sdkHbarAmount.toString()} from ${\n            this.kit.userAccountId\n          } to ${recipientAccountId.toString()}`\n        );\n        \n        this.addNote(\n          `Configured HBAR transfer from your account (${\n            this.kit.userAccountId\n          }) to ${recipientAccountId.toString()} for ${sdkHbarAmount.toString()}.`\n        );\n\n        transaction.addHbarTransfer(recipientAccountId, sdkHbarAmount);\n        transaction.addHbarTransfer(\n          AccountId.fromString(this.kit.userAccountId),\n          sdkHbarAmount.negated()\n        );\n\n        userTransferProcessedForScheduling = true;\n      }\n    }\n\n    if (!userTransferProcessedForScheduling) {\n      const processedTransfers: Array<{\n        accountId: AccountId;\n        amount: BigNumber;\n        hbar: Hbar;\n      }> = [];\n      \n      for (const transferInput of params.transfers) {\n        const accountId =\n          typeof transferInput.accountId === 'string'\n            ? AccountId.fromString(transferInput.accountId)\n            : transferInput.accountId;\n\n        const amountValue =\n          typeof transferInput.amount === 'string' ||\n          typeof transferInput.amount === 'number'\n            ? transferInput.amount\n            : transferInput.amount.toString();\n\n        const amountBigNum = new BigNumber(amountValue);\n        const roundedAmount = amountBigNum.toFixed(8, BigNumber.ROUND_DOWN);\n        \n        this.logger.info(\n          `Processing transfer: ${amountValue} HBAR (rounded to ${roundedAmount}) for account ${accountId.toString()}`\n        );\n\n        const sdkHbarAmount = Hbar.fromString(roundedAmount);\n        processedTransfers.push({\n          accountId,\n          amount: amountBigNum,\n          hbar: sdkHbarAmount\n        });\n\n        const tinybarsContribution = sdkHbarAmount.toTinybars();\n        netZeroInTinybars = netZeroInTinybars.plus(\n          tinybarsContribution.toString()\n        );\n      }\n\n      if (!netZeroInTinybars.isZero()) {\n        this.logger.warn(\n          `Transfer sum not zero: ${netZeroInTinybars.toString()} tinybars off. Adjusting last transfer.`\n        );\n        \n        if (processedTransfers.length > 0) {\n          const lastTransfer = processedTransfers[processedTransfers.length - 1];\n          const adjustment = netZeroInTinybars.dividedBy(-100000000);\n          const adjustedAmount = lastTransfer.amount.plus(adjustment);\n          const adjustedRounded = adjustedAmount.toFixed(8, BigNumber.ROUND_DOWN);\n          lastTransfer.hbar = Hbar.fromString(adjustedRounded);\n          \n          this.logger.info(\n            `Adjusted last transfer for ${lastTransfer.accountId.toString()} to ${adjustedRounded} HBAR`\n          );\n        }\n      }\n      \n      for (const transfer of processedTransfers) {\n        transaction.addHbarTransfer(transfer.accountId, transfer.hbar);\n      }\n    }\n\n    if (typeof params.memo !== 'undefined') {\n      if (params.memo === null) {\n        this.logger.warn('Received null for memo in transferHbar.');\n      } else {\n        transaction.setTransactionMemo(params.memo);\n      }\n    }\n\n    this.setCurrentTransaction(transaction);\n    return this;\n  }\n}"],"names":[],"mappings":"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"}

package/dist/esm/index25.js

@@ -1,30 +1,68 @@
-const DEFAULT_CONTENT_REFERENCE_CONFIG = {
-  sizeThresholdBytes: 10 * 1024,
-  maxAgeMs: 60 * 60 * 1e3,
-  maxReferences: 100,
-  maxTotalStorageBytes: 100 * 1024 * 1024,
-  enableAutoCleanup: true,
-  cleanupIntervalMs: 5 * 60 * 1e3,
-  enablePersistence: false,
-  storageBackend: "memory",
-  cleanupPolicies: {
-    recent: { maxAgeMs: 30 * 60 * 1e3, priority: 1 },
-    userContent: { maxAgeMs: 2 * 60 * 60 * 1e3, priority: 2 },
-    agentGenerated: { maxAgeMs: 60 * 60 * 1e3, priority: 3 },
-    default: { maxAgeMs: 60 * 60 * 1e3, priority: 4 }
+import { createHash } from "crypto";
+class ReferenceIdGenerator {
+  /**
+   * Generate a content-based reference ID using SHA-256 hashing
+   * 
+   * @param content The content to generate a reference ID for
+   * @returns Deterministic reference ID based on content hash
+   */
+  static generateId(content) {
+    const hash = createHash("sha256");
+    hash.update(content);
+    return hash.digest("hex");
   }
-};
-class ContentReferenceError extends Error {
-  constructor(message, type, referenceId, suggestedActions) {
-    super(message);
-    this.type = type;
-    this.referenceId = referenceId;
-    this.suggestedActions = suggestedActions;
-    this.name = "ContentReferenceError";
+  /**
+   * Validate that a string is a properly formatted reference ID
+   * 
+   * @param id The ID to validate
+   * @returns true if the ID is valid format
+   */
+  static isValidReferenceId(id) {
+    if (!id || typeof id !== "string") {
+      return false;
+    }
+    if (id.length !== 64) {
+      return false;
+    }
+    return /^[a-f0-9]+$/.test(id);
+  }
+  /**
+   * Extract reference ID from ref:// format
+   * 
+   * @param input Input string that may contain a reference ID
+   * @returns Extracted reference ID or null if not found
+   */
+  static extractReferenceId(input) {
+    if (!input || typeof input !== "string") {
+      return null;
+    }
+    const refFormatMatch = input.match(/^ref:\/\/([a-f0-9]{64})$/);
+    if (refFormatMatch) {
+      return refFormatMatch[1];
+    }
+    return this.isValidReferenceId(input) ? input : null;
+  }
+  /**
+   * Format a reference ID in the standard ref:// format
+   * 
+   * @param referenceId The reference ID to format
+   * @returns Formatted reference string
+   */
+  static formatReference(referenceId) {
+    return `ref://${referenceId}`;
+  }
+  /**
+   * Generate a test reference ID (for testing purposes only)
+   * 
+   * @param testSeed A test seed to generate a fake but valid ID format
+   * @returns A valid format reference ID for testing
+   */
+  static generateTestId(testSeed) {
+    const content = Buffer.from(`test-${testSeed}-${Date.now()}`);
+    return this.generateId(content);
   }
 }
 export {
-  ContentReferenceError,
-  DEFAULT_CONTENT_REFERENCE_CONFIG
+  ReferenceIdGenerator
 };
 //# sourceMappingURL=index25.js.map

package/dist/esm/index25.js.map

@@ -1 +1 @@
-{"version":3,"file":"index25.js","sources":["../../src/types/content-reference.ts"],"sourcesContent":["/**\n * Content Reference System Types\n * \n * Shared interfaces for the Reference-Based Content System that handles\n * large content storage with unique reference IDs to optimize context window usage.\n */\n\n/**\n * Unique identifier for stored content references\n * Format: Cryptographically secure 32-byte identifier with base64url encoding\n */\nexport type ReferenceId = string;\n\n/**\n * Lifecycle state of a content reference\n */\nexport type ReferenceLifecycleState = 'active' | 'expired' | 'cleanup_pending' | 'invalid';\n\n/**\n * Content types supported by the reference system\n */\nexport type ContentType = 'text' | 'json' | 'html' | 'markdown' | 'binary' | 'unknown';\n\n/**\n * Sources that created the content reference\n */\nexport type ContentSource = 'mcp_tool' | 'user_upload' | 'agent_generated' | 'system';\n\n/**\n * Metadata associated with stored content\n */\nexport interface ContentMetadata {\n  /** Content type classification */\n  contentType: ContentType;\n  \n  /** MIME type of the original content */\n  mimeType?: string;\n  \n  /** Size in bytes of the stored content */\n  sizeBytes: number;\n  \n  /** When the content was originally stored */\n  createdAt: Date;\n  \n  /** Last time the content was accessed via reference resolution */\n  lastAccessedAt: Date;\n  \n  /** Source that created this content reference */\n  source: ContentSource;\n  \n  /** Name of the MCP tool that generated the content (if applicable) */\n  mcpToolName?: string;\n  \n  /** Original filename or suggested name for the content */\n  fileName?: string;\n  \n  /** Number of times this reference has been resolved */\n  accessCount: number;\n  \n  /** Tags for categorization and cleanup policies */\n  tags?: string[];\n  \n  /** Custom metadata from the source */\n  customMetadata?: Record<string, unknown>;\n}\n\n/**\n * Core content reference object passed through agent context\n * Designed to be lightweight (<100 tokens) while providing enough \n * information for agent decision-making\n */\nexport interface ContentReference {\n  /** Unique identifier for resolving the content */\n  referenceId: ReferenceId;\n  \n  /** Current lifecycle state */\n  state: ReferenceLifecycleState;\n  \n  /** Brief description or preview of the content (max 200 chars) */\n  preview: string;\n  \n  /** Essential metadata for agent decision-making */\n  metadata: Pick<ContentMetadata, 'contentType' | 'sizeBytes' | 'source' | 'fileName' | 'mimeType'>;\n  \n  /** When this reference was created */\n  createdAt: Date;\n  \n  /** Special format indicator for reference IDs in content */\n  readonly format: 'ref://{id}';\n}\n\n/**\n * Result of attempting to resolve a content reference\n */\nexport interface ReferenceResolutionResult {\n  /** Whether the resolution was successful */\n  success: boolean;\n  \n  /** The resolved content if successful */\n  content?: Buffer;\n  \n  /** Complete metadata if successful */\n  metadata?: ContentMetadata;\n  \n  /** Error message if resolution failed */\n  error?: string;\n  \n  /** Specific error type for targeted error handling */\n  errorType?: 'not_found' | 'expired' | 'corrupted' | 'access_denied' | 'system_error';\n  \n  /** Suggested actions for recovery */\n  suggestedActions?: string[];\n}\n\n/**\n * Configuration for content reference storage and lifecycle\n */\nexport interface ContentReferenceConfig {\n  /** Size threshold above which content should be stored as references (default: 10KB) */\n  sizeThresholdBytes: number;\n  \n  /** Maximum age for unused references before cleanup (default: 1 hour) */\n  maxAgeMs: number;\n  \n  /** Maximum number of references to store simultaneously */\n  maxReferences: number;\n  \n  /** Maximum total storage size for all references */\n  maxTotalStorageBytes: number;\n  \n  /** Whether to enable automatic cleanup */\n  enableAutoCleanup: boolean;\n  \n  /** Interval for cleanup checks in milliseconds */\n  cleanupIntervalMs: number;\n  \n  /** Whether to persist references across restarts */\n  enablePersistence: boolean;\n  \n  /** Storage backend configuration */\n  storageBackend: 'memory' | 'filesystem' | 'hybrid';\n  \n  /** Cleanup policies for different content types */\n  cleanupPolicies: {\n    /** Policy for content marked as \"recent\" from MCP tools */\n    recent: { maxAgeMs: number; priority: number };\n    \n    /** Policy for user-uploaded content */\n    userContent: { maxAgeMs: number; priority: number };\n    \n    /** Policy for agent-generated content */\n    agentGenerated: { maxAgeMs: number; priority: number };\n    \n    /** Default policy for other content */\n    default: { maxAgeMs: number; priority: number };\n  };\n}\n\n/**\n * Default configuration values\n */\nexport const DEFAULT_CONTENT_REFERENCE_CONFIG: ContentReferenceConfig = {\n  sizeThresholdBytes: 10 * 1024,\n  maxAgeMs: 60 * 60 * 1000,\n  maxReferences: 100,\n  maxTotalStorageBytes: 100 * 1024 * 1024,\n  enableAutoCleanup: true,\n  cleanupIntervalMs: 5 * 60 * 1000,\n  enablePersistence: false,\n  storageBackend: 'memory',\n  cleanupPolicies: {\n    recent: { maxAgeMs: 30 * 60 * 1000, priority: 1 },\n    userContent: { maxAgeMs: 2 * 60 * 60 * 1000, priority: 2 },\n    agentGenerated: { maxAgeMs: 60 * 60 * 1000, priority: 3 },\n    default: { maxAgeMs: 60 * 60 * 1000, priority: 4 }\n  }\n};\n\n/**\n * Statistics about content reference usage and storage\n */\nexport interface ContentReferenceStats {\n  /** Total number of active references */\n  activeReferences: number;\n  \n  /** Total storage used by all references in bytes */\n  totalStorageBytes: number;\n  \n  /** Number of references cleaned up in last cleanup cycle */\n  recentlyCleanedUp: number;\n  \n  /** Number of successful reference resolutions since startup */\n  totalResolutions: number;\n  \n  /** Number of failed resolution attempts */\n  failedResolutions: number;\n  \n  /** Average content size in bytes */\n  averageContentSize: number;\n  \n  /** Most frequently accessed reference ID */\n  mostAccessedReferenceId?: ReferenceId;\n  \n  /** Storage utilization percentage */\n  storageUtilization: number;\n  \n  /** Performance metrics */\n  performanceMetrics: {\n    /** Average time to create a reference in milliseconds */\n    averageCreationTimeMs: number;\n    \n    /** Average time to resolve a reference in milliseconds */\n    averageResolutionTimeMs: number;\n    \n    /** Average cleanup time in milliseconds */\n    averageCleanupTimeMs: number;\n  };\n}\n\n/**\n * Error types for content reference operations\n */\nexport class ContentReferenceError extends Error {\n  constructor(\n    message: string,\n    public readonly type: ReferenceResolutionResult['errorType'],\n    public readonly referenceId?: ReferenceId,\n    public readonly suggestedActions?: string[]\n  ) {\n    super(message);\n    this.name = 'ContentReferenceError';\n  }\n}\n\n/**\n * Interface for content reference storage implementations\n */\nexport interface ContentReferenceStore {\n  /**\n   * Store content and return a reference\n   */\n  storeContent(\n    content: Buffer,\n    metadata: Omit<ContentMetadata, 'createdAt' | 'lastAccessedAt' | 'accessCount'>\n  ): Promise<ContentReference>;\n  \n  /**\n   * Resolve a reference to its content\n   */\n  resolveReference(referenceId: ReferenceId): Promise<ReferenceResolutionResult>;\n  \n  /**\n   * Check if a reference exists and is valid\n   */\n  hasReference(referenceId: ReferenceId): Promise<boolean>;\n  \n  /**\n   * Mark a reference for cleanup\n   */\n  cleanupReference(referenceId: ReferenceId): Promise<boolean>;\n  \n  /**\n   * Get current storage statistics\n   */\n  getStats(): Promise<ContentReferenceStats>;\n  \n  /**\n   * Update configuration\n   */\n  updateConfig(config: Partial<ContentReferenceConfig>): Promise<void>;\n  \n  /**\n   * Perform cleanup based on current policies\n   */\n  performCleanup(): Promise<{ cleanedUp: number; errors: string[] }>;\n  \n  /**\n   * Dispose of resources\n   */\n  dispose(): Promise<void>;\n}"],"names":[],"mappings":"AAiKO,MAAM,mCAA2D;AAAA,EACtE,oBAAoB,KAAK;AAAA,EACzB,UAAU,KAAK,KAAK;AAAA,EACpB,eAAe;AAAA,EACf,sBAAsB,MAAM,OAAO;AAAA,EACnC,mBAAmB;AAAA,EACnB,mBAAmB,IAAI,KAAK;AAAA,EAC5B,mBAAmB;AAAA,EACnB,gBAAgB;AAAA,EAChB,iBAAiB;AAAA,IACf,QAAQ,EAAE,UAAU,KAAK,KAAK,KAAM,UAAU,EAAA;AAAA,IAC9C,aAAa,EAAE,UAAU,IAAI,KAAK,KAAK,KAAM,UAAU,EAAA;AAAA,IACvD,gBAAgB,EAAE,UAAU,KAAK,KAAK,KAAM,UAAU,EAAA;AAAA,IACtD,SAAS,EAAE,UAAU,KAAK,KAAK,KAAM,UAAU,EAAA;AAAA,EAAE;AAErD;AA8CO,MAAM,8BAA8B,MAAM;AAAA,EAC/C,YACE,SACgB,MACA,aACA,kBAChB;AACA,UAAM,OAAO;AAJG,SAAA,OAAA;AACA,SAAA,cAAA;AACA,SAAA,mBAAA;AAGhB,SAAK,OAAO;AAAA,EACd;AACF;"}
+{"version":3,"file":"index25.js","sources":["../../src/memory/ReferenceIdGenerator.ts"],"sourcesContent":["import { createHash } from 'crypto';\nimport { ReferenceId } from '../types/content-reference';\n\n/**\n * Content-based reference ID generator using SHA-256 (HCS-1 style)\n * \n * Generates deterministic reference IDs based on content hashing.\n * Same content always produces the same reference ID.\n */\nexport class ReferenceIdGenerator {\n  /**\n   * Generate a content-based reference ID using SHA-256 hashing\n   * \n   * @param content The content to generate a reference ID for\n   * @returns Deterministic reference ID based on content hash\n   */\n  static generateId(content: Buffer): ReferenceId {\n    const hash = createHash('sha256');\n    hash.update(content);\n    return hash.digest('hex');\n  }\n  \n  /**\n   * Validate that a string is a properly formatted reference ID\n   * \n   * @param id The ID to validate\n   * @returns true if the ID is valid format\n   */\n  static isValidReferenceId(id: string): id is ReferenceId {\n    if (!id || typeof id !== 'string') {\n      return false;\n    }\n    \n    if (id.length !== 64) {\n      return false;\n    }\n    \n    return /^[a-f0-9]+$/.test(id);\n  }\n  \n  /**\n   * Extract reference ID from ref:// format\n   * \n   * @param input Input string that may contain a reference ID\n   * @returns Extracted reference ID or null if not found\n   */\n  static extractReferenceId(input: string): ReferenceId | null {\n    if (!input || typeof input !== 'string') {\n      return null;\n    }\n    \n    const refFormatMatch = input.match(/^ref:\\/\\/([a-f0-9]{64})$/);\n    if (refFormatMatch) {\n      return refFormatMatch[1] as ReferenceId;\n    }\n    \n    return this.isValidReferenceId(input) ? input : null;\n  }\n  \n  /**\n   * Format a reference ID in the standard ref:// format\n   * \n   * @param referenceId The reference ID to format\n   * @returns Formatted reference string\n   */\n  static formatReference(referenceId: ReferenceId): string {\n    return `ref://${referenceId}`;\n  }\n  \n  /**\n   * Generate a test reference ID (for testing purposes only)\n   * \n   * @param testSeed A test seed to generate a fake but valid ID format\n   * @returns A valid format reference ID for testing\n   */\n  static generateTestId(testSeed: string): ReferenceId {\n    const content = Buffer.from(`test-${testSeed}-${Date.now()}`);\n    return this.generateId(content);\n  }\n}"],"names":[],"mappings":";AASO,MAAM,qBAAqB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOhC,OAAO,WAAW,SAA8B;AAC9C,UAAM,OAAO,WAAW,QAAQ;AAChC,SAAK,OAAO,OAAO;AACnB,WAAO,KAAK,OAAO,KAAK;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAO,mBAAmB,IAA+B;AACvD,QAAI,CAAC,MAAM,OAAO,OAAO,UAAU;AACjC,aAAO;AAAA,IACT;AAEA,QAAI,GAAG,WAAW,IAAI;AACpB,aAAO;AAAA,IACT;AAEA,WAAO,cAAc,KAAK,EAAE;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAO,mBAAmB,OAAmC;AAC3D,QAAI,CAAC,SAAS,OAAO,UAAU,UAAU;AACvC,aAAO;AAAA,IACT;AAEA,UAAM,iBAAiB,MAAM,MAAM,0BAA0B;AAC7D,QAAI,gBAAgB;AAClB,aAAO,eAAe,CAAC;AAAA,IACzB;AAEA,WAAO,KAAK,mBAAmB,KAAK,IAAI,QAAQ;AAAA,EAClD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAO,gBAAgB,aAAkC;AACvD,WAAO,SAAS,WAAW;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAO,eAAe,UAA+B;AACnD,UAAM,UAAU,OAAO,KAAK,QAAQ,QAAQ,IAAI,KAAK,IAAA,CAAK,EAAE;AAC5D,WAAO,KAAK,WAAW,OAAO;AAAA,EAChC;AACF;"}