@t2000/engine 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -2046,6 +2046,7 @@ declare const balanceCheckTool: Tool<{
     saveableUsdsui: number;
     address: string;
     isSelfQuery: boolean;
+    suinsName: string | null;
 }>;
 
 declare const savingsInfoTool: Tool<{
@@ -2053,6 +2054,7 @@ declare const savingsInfoTool: Tool<{
 }, {
     address: string;
     isSelfQuery: boolean;
+    suinsName: string | null;
     positions: PositionEntry[];
     earnings: {
         totalYieldEarned: number;
@@ -2080,6 +2082,7 @@ declare const healthCheckTool: Tool<{
     status: string;
     address: string;
     isSelfQuery: boolean;
+    suinsName: string | null;
 }>;
 
 type RateMap = Record<string, {
@@ -2332,6 +2335,16 @@ interface PortfolioResult {
     dailyEarning?: number;
     weekChange?: WeekChange;
     priceSource: AddressPortfolio['source'];
+    /** Resolved on-chain address (post SuiNS normalization). */
+    address?: string;
+    /** True when the resolved address matches the signed-in wallet. */
+    isSelfQuery?: boolean;
+    /**
+     * Original SuiNS name when the user passed `address: "alex.sui"`,
+     * otherwise null. Host cards use this to title the result with the
+     * human-readable name instead of the truncated 0x address.
+     */
+    suinsName?: string | null;
 }
 declare const portfolioAnalysisTool: Tool<{
     address?: string | undefined;
@@ -2397,12 +2410,25 @@ interface ActivitySummary {
     yieldEarnedUsd: number;
     address?: string;
     isSelfQuery?: boolean;
+    suinsName?: string | null;
 }
 declare const activitySummaryTool: Tool<{
     address?: string | undefined;
     period?: "month" | "year" | "all" | "week" | undefined;
 }, ActivitySummary>;
 
+interface ResolveSuinsResult {
+    /** The lookup name, lowercased and trimmed. */
+    name: string;
+    /** The resolved 0x address, or null when the name isn't registered. */
+    address: string | null;
+    /** True when the name resolves to an address. */
+    registered: boolean;
+}
+declare const resolveSuinsTool: Tool<{
+    name: string;
+}, ResolveSuinsResult>;
+
 declare const tokenPricesTool: Tool<{
     coinTypes: string[];
     include24hChange?: boolean | undefined;
@@ -2481,6 +2507,98 @@ interface WalletCoin {
  */
 declare function fetchWalletCoins(address: string, rpcUrl?: string): Promise<WalletCoin[]>;
 
+/**
+ * Canonical 0x-address shape. Loose lower bound (>= 1 hex char) so
+ * pre-v1.0 short addresses still validate; tools that need a full 64-hex
+ * address can additionally check `length === 66`. Case-insensitive on
+ * the `0x` prefix because some upstream callers (and historic tests)
+ * uppercase the prefix as part of address normalization tests; the
+ * normalizer always returns the lowercased canonical form regardless.
+ */
+declare const SUI_ADDRESS_REGEX: RegExp;
+/**
+ * Strict canonical 0x-address shape (66 chars total). Used by the
+ * resolver's "looks like" check to disambiguate "user pasted an
+ * address" vs "user typed a SuiNS name".
+ */
+declare const SUI_ADDRESS_STRICT_REGEX: RegExp;
+/**
+ * Mirrors the pattern in `audric/apps/web/lib/suins-resolver.ts` so the
+ * host-side send executor and the engine-side read normalizer agree on
+ * what counts as a SuiNS name. SuiNS allows nested labels (`team.alex.sui`)
+ * but every label must use only `[a-z0-9-]`.
+ */
+declare const SUINS_NAME_REGEX: RegExp;
+declare class InvalidAddressError extends Error {
+    readonly raw: string;
+    constructor(raw: string);
+}
+declare class SuinsNotRegisteredError extends Error {
+    readonly name_: string;
+    constructor(name_: string);
+}
+declare class SuinsRpcError extends Error {
+    readonly name_: string;
+    constructor(name_: string, detail: string);
+}
+/**
+ * Returns true if `value` looks like a SuiNS name (case-insensitive).
+ * Cheap synchronous check — use to avoid an unnecessary RPC round-trip
+ * for inputs that obviously aren't names (0x addresses, contact handles).
+ */
+declare function looksLikeSuiNs(value: string): boolean;
+/**
+ * Resolve a SuiNS name to its on-chain Sui address via the public
+ * `suix_resolveNameServiceAddress` JSON-RPC method. Returns `null` if
+ * the name resolves to no address (= not registered or expired). Throws
+ * `SuinsRpcError` on RPC/network failure.
+ *
+ * The host SHOULD pass a `rpcUrl` that includes any vendor key (e.g.
+ * audric's BlockVision-keyed URL) so the call benefits from the host's
+ * paid retry/cache budget. Falls back to the public mainnet endpoint.
+ */
+declare function resolveSuinsViaRpc(rawName: string, ctx?: {
+    suiRpcUrl?: string;
+    signal?: AbortSignal;
+}): Promise<string | null>;
+interface NormalizedAddress {
+    /**
+     * Canonical 0x-prefixed lowercase hex address. Always set on success.
+     * Tools should use this for any downstream query (BlockVision, NAVI,
+     * positionFetcher, etc.) and for cache keys.
+     */
+    address: string;
+    /**
+     * The user-facing name when the input was resolved via SuiNS, otherwise
+     * `null`. Tools should stamp this on result data so card titles can
+     * render "Balance · obehi.sui" instead of "Balance · 0x1234…abcd".
+     */
+    suinsName: string | null;
+    /**
+     * The original input (pre-normalization). Useful for error narration —
+     * "I tried to resolve `Obehi.Sui` and …" reads better than the
+     * post-trim/lowercase form.
+     */
+    raw: string;
+}
+/**
+ * Canonical normalizer. Accepts a 0x address OR a SuiNS name; returns
+ * a structured `NormalizedAddress`. Throws:
+ *   - `InvalidAddressError` if the input matches neither shape.
+ *   - `SuinsNotRegisteredError` if the SuiNS name is well-formed but
+ *     resolves to null (= not registered).
+ *   - `SuinsRpcError` if the RPC fails.
+ *
+ * Every read tool that accepts a user-supplied `address` parameter MUST
+ * call this helper before any downstream lookup. Doing the check inline
+ * (1) duplicates the regex, (2) silently rejects SuiNS names, (3) makes
+ * cache keys inconsistent across tools (some lowercase, some not).
+ */
+declare function normalizeAddressInput(value: string, ctx?: {
+    suiRpcUrl?: string;
+    signal?: AbortSignal;
+}): Promise<NormalizedAddress>;
+
 /** Cache entry stored under each address key. */
 interface DefiCacheEntry {
     data: DefiSummary;
@@ -2879,4 +2997,4 @@ declare function getTelemetrySink(): TelemetrySink;
 /** Restore the default noop sink. Used by test teardowns. */
 declare function resetTelemetrySink(): void;
 
-export { type AddressPortfolio, AnthropicProvider, type AnthropicProviderConfig, type AudricHistoryRecord, type AudricPortfolioResult, type AwaitOrFetchOpts, type BalancePrices, type BalanceResult, BalanceTracker, type BuildToolOptions, CANVAS_TEMPLATES, type CanvasTemplate, type ChatParams, type CompactOptions, type ContentBlock, ContextBudget, type ContextBudgetConfig, type ConversationState, type ConversationStateStore, type CostSnapshot, CostTracker, type CostTrackerConfig, DEFAULT_GUARD_CONFIG, DEFAULT_LEASE_SEC, DEFAULT_PERMISSION_CONFIG, DEFAULT_POLL_BUDGET_MS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_SYSTEM_PROMPT, type DefiCacheEntry, type DefiCacheStore, type DefiProtocol, type DefiSummary, EarlyToolDispatcher, type EngineConfig, type EngineEvent, type FetchLock, type GuardCheckResult, type GuardConfig, type GuardEvent, type GuardInjection, type GuardResult, type GuardRunnerState, type GuardTier, type GuardVerdict, type HealthFactorResult, InMemoryDefiCacheStore, InMemoryFetchLock, InMemoryNaviCacheStore, InMemoryWalletCacheStore, type LLMProvider, type McpCallResult, McpClientManager, McpResponseCache, type McpServerConfig, type McpServerConnection, type McpToolAdapterConfig, type McpToolDescriptor, MemorySessionStore, type Message, NAVI_ADDR_TTL_SEC, NAVI_MCP_CONFIG, NAVI_MCP_URL, NAVI_RATES_TTL_SEC, NAVI_SERVER_NAME, type NaviCacheEntry, type NaviCacheStore, type NaviRawCoin, type NaviRawHealthFactor, type NaviRawPool, type NaviRawPosition, type NaviRawPositionsResponse, type NaviRawProtocolStats, type NaviRawRewardsResponse, type NaviReadOptions, NaviTools, type OutputConfig, PERMISSION_PRESETS, type PendingAction, type PendingActionModifiableField, type PendingReward, type PendingToolCall, type PermissionLevel, type PermissionOperation, type PermissionResponse, type PermissionRule, type PortfolioCoin, type PositionEntry, type PreflightResult, type ProtocolStats, type ProviderEvent, QueryEngine, READ_TOOLS, type RatesResult, type Recipe, type RecipePrerequisite, RecipeRegistry, type RecipeStep, type RecipeStepOnError, RetryTracker, type SSEEvent, type SavingsResult, type ServerPositionData, type SessionData, type SessionStore, type StateType, type StopReason, type SuiCoinBalance, type SystemBlock, type SystemPrompt, TOOL_FLAGS, TOOL_MODIFIABLE_FIELDS, type TelemetrySink, type TelemetryTags, type ThinkingConfig, type ThinkingEffort, type Tool, type ToolChoice, type ToolContext, type ToolDefinition, type ToolFlags, type ToolJsonSchema, type ToolResult, TxMutex, type UserFinancialProfile, type UserPermissionConfig, WRITE_TOOLS, type WalletCacheEntry, type WalletCacheStore, type WalletCoin, _resetNaviCircuitBreaker, activitySummaryTool, adaptAllMcpTools, adaptAllServerTools, adaptMcpTool, applyToolFlags, awaitOrFetch, balanceCheckTool, borrowTool, budgetToolResult, buildCachedSystemPrompt, buildMcpTools, buildProactivenessInstructions, buildProfileContext, buildSelfEvaluationInstruction, buildStateContext, buildTool, claimRewardsTool, classifyEffort, clearPortfolioCache, clearPortfolioCacheFor, clearPriceMapCache, compactMessages, createGuardRunnerState, engineToSSE, estimateTokens, explainTxTool, extractConversationText, extractMcpText, fetchAddressDefiPortfolio, fetchAddressPortfolio, fetchAudricHistory, fetchAudricPortfolio, fetchAvailableRewards, fetchBalance, fetchHealthFactor, fetchPositions, fetchProtocolStats, fetchRates, fetchSavings, fetchTokenPrices, fetchWalletCoins, findTool, getAudricApiBase, getDefaultTools, getDefiCacheStore, getFetchLock, getMcpManager, getModifiableFields, getNaviCacheStore, getTelemetrySink, getToolFlags, getWalletAddress, getWalletCacheStore, guardArtifactPreview, guardStaleData, hasNaviMcp, healthCheckTool, loadRecipes, microcompact, mppServicesTool, naviKey, parseMcpJson, parseRecipe, parseSSE, payApiTool, portfolioAnalysisTool, protocolDeepDiveTool, ratesInfoTool, registerEngineTools, renderCanvasTool, repayDebtTool, requireAgent, resetDefiCacheStore, resetFetchLock, resetNaviCacheStore, resetTelemetrySink, resetWalletCacheStore, resolvePermissionTier, resolveUsdValue, runGuards, runTools, saveContactTool, saveDepositTool, savingsInfoTool, sendTransferTool, serializeSSE, setDefiCacheStore, setFetchLock, setNaviCacheStore, setTelemetrySink, setWalletCacheStore, spendingAnalyticsTool, swapExecuteTool, swapQuoteTool, tokenPricesTool, toolNameToOperation, toolsToDefinitions, transactionHistoryTool, transformBalance, transformHealthFactor, transformPositions, transformRates, transformRewards, transformSavings, updateGuardStateAfterToolResult, validateHistory, voloStakeTool, voloStatsTool, voloUnstakeTool, webSearchTool, withdrawTool, yieldSummaryTool };
+export { type AddressPortfolio, AnthropicProvider, type AnthropicProviderConfig, type AudricHistoryRecord, type AudricPortfolioResult, type AwaitOrFetchOpts, type BalancePrices, type BalanceResult, BalanceTracker, type BuildToolOptions, CANVAS_TEMPLATES, type CanvasTemplate, type ChatParams, type CompactOptions, type ContentBlock, ContextBudget, type ContextBudgetConfig, type ConversationState, type ConversationStateStore, type CostSnapshot, CostTracker, type CostTrackerConfig, DEFAULT_GUARD_CONFIG, DEFAULT_LEASE_SEC, DEFAULT_PERMISSION_CONFIG, DEFAULT_POLL_BUDGET_MS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_SYSTEM_PROMPT, type DefiCacheEntry, type DefiCacheStore, type DefiProtocol, type DefiSummary, EarlyToolDispatcher, type EngineConfig, type EngineEvent, type FetchLock, type GuardCheckResult, type GuardConfig, type GuardEvent, type GuardInjection, type GuardResult, type GuardRunnerState, type GuardTier, type GuardVerdict, type HealthFactorResult, InMemoryDefiCacheStore, InMemoryFetchLock, InMemoryNaviCacheStore, InMemoryWalletCacheStore, InvalidAddressError, type LLMProvider, type McpCallResult, McpClientManager, McpResponseCache, type McpServerConfig, type McpServerConnection, type McpToolAdapterConfig, type McpToolDescriptor, MemorySessionStore, type Message, NAVI_ADDR_TTL_SEC, NAVI_MCP_CONFIG, NAVI_MCP_URL, NAVI_RATES_TTL_SEC, NAVI_SERVER_NAME, type NaviCacheEntry, type NaviCacheStore, type NaviRawCoin, type NaviRawHealthFactor, type NaviRawPool, type NaviRawPosition, type NaviRawPositionsResponse, type NaviRawProtocolStats, type NaviRawRewardsResponse, type NaviReadOptions, NaviTools, type NormalizedAddress, type OutputConfig, PERMISSION_PRESETS, type PendingAction, type PendingActionModifiableField, type PendingReward, type PendingToolCall, type PermissionLevel, type PermissionOperation, type PermissionResponse, type PermissionRule, type PortfolioCoin, type PositionEntry, type PreflightResult, type ProtocolStats, type ProviderEvent, QueryEngine, READ_TOOLS, type RatesResult, type Recipe, type RecipePrerequisite, RecipeRegistry, type RecipeStep, type RecipeStepOnError, RetryTracker, type SSEEvent, SUINS_NAME_REGEX, SUI_ADDRESS_REGEX, SUI_ADDRESS_STRICT_REGEX, type SavingsResult, type ServerPositionData, type SessionData, type SessionStore, type StateType, type StopReason, type SuiCoinBalance, SuinsNotRegisteredError, SuinsRpcError, type SystemBlock, type SystemPrompt, TOOL_FLAGS, TOOL_MODIFIABLE_FIELDS, type TelemetrySink, type TelemetryTags, type ThinkingConfig, type ThinkingEffort, type Tool, type ToolChoice, type ToolContext, type ToolDefinition, type ToolFlags, type ToolJsonSchema, type ToolResult, TxMutex, type UserFinancialProfile, type UserPermissionConfig, WRITE_TOOLS, type WalletCacheEntry, type WalletCacheStore, type WalletCoin, _resetNaviCircuitBreaker, activitySummaryTool, adaptAllMcpTools, adaptAllServerTools, adaptMcpTool, applyToolFlags, awaitOrFetch, balanceCheckTool, borrowTool, budgetToolResult, buildCachedSystemPrompt, buildMcpTools, buildProactivenessInstructions, buildProfileContext, buildSelfEvaluationInstruction, buildStateContext, buildTool, claimRewardsTool, classifyEffort, clearPortfolioCache, clearPortfolioCacheFor, clearPriceMapCache, compactMessages, createGuardRunnerState, engineToSSE, estimateTokens, explainTxTool, extractConversationText, extractMcpText, fetchAddressDefiPortfolio, fetchAddressPortfolio, fetchAudricHistory, fetchAudricPortfolio, fetchAvailableRewards, fetchBalance, fetchHealthFactor, fetchPositions, fetchProtocolStats, fetchRates, fetchSavings, fetchTokenPrices, fetchWalletCoins, findTool, getAudricApiBase, getDefaultTools, getDefiCacheStore, getFetchLock, getMcpManager, getModifiableFields, getNaviCacheStore, getTelemetrySink, getToolFlags, getWalletAddress, getWalletCacheStore, guardArtifactPreview, guardStaleData, hasNaviMcp, healthCheckTool, loadRecipes, looksLikeSuiNs, microcompact, mppServicesTool, naviKey, normalizeAddressInput, parseMcpJson, parseRecipe, parseSSE, payApiTool, portfolioAnalysisTool, protocolDeepDiveTool, ratesInfoTool, registerEngineTools, renderCanvasTool, repayDebtTool, requireAgent, resetDefiCacheStore, resetFetchLock, resetNaviCacheStore, resetTelemetrySink, resetWalletCacheStore, resolvePermissionTier, resolveSuinsTool, resolveSuinsViaRpc, resolveUsdValue, runGuards, runTools, saveContactTool, saveDepositTool, savingsInfoTool, sendTransferTool, serializeSSE, setDefiCacheStore, setFetchLock, setNaviCacheStore, setTelemetrySink, setWalletCacheStore, spendingAnalyticsTool, swapExecuteTool, swapQuoteTool, tokenPricesTool, toolNameToOperation, toolsToDefinitions, transactionHistoryTool, transformBalance, transformHealthFactor, transformPositions, transformRates, transformRewards, transformSavings, updateGuardStateAfterToolResult, validateHistory, voloStakeTool, voloStatsTool, voloUnstakeTool, webSearchTool, withdrawTool, yieldSummaryTool };