helius-mcp 1.3.0 → 2.1.0

package/dist/router/catalog.js

@@ -0,0 +1,394 @@
+import { HELIUS_ACCOUNT_ACTIONS, HELIUS_ASSET_ACTIONS, HELIUS_CHAIN_ACTIONS, HELIUS_COMPRESSION_ACTIONS, HELIUS_KNOWLEDGE_ACTIONS, HELIUS_STREAMING_ACTIONS, HELIUS_TRANSACTION_ACTIONS, HELIUS_WALLET_ACTIONS, HELIUS_WRITE_ACTIONS, ACTION_NAMES, } from './actions.js';
+import { findPublicToolForAction } from './action-groups.js';
+const always = { kind: 'always' };
+function gate(minimumPlan, label, variants) {
+    return {
+        baseline: {
+            id: `${minimumPlan}:${label}`,
+            minimumPlan,
+            predicate: always,
+            label,
+        },
+        ...(variants ? { variants } : {}),
+    };
+}
+function makeEntry(action, overrides = {}) {
+    const publicTool = overrides.publicTool ?? findPublicToolForAction(action);
+    const responseFamily = overrides.responseFamily ?? 'record';
+    const defaultDetail = overrides.defaultDetail ?? (responseFamily === 'scalar' || responseFamily === 'mutationReceipt'
+        ? 'full'
+        : responseFamily === 'document' || responseFamily === 'streamingConfig' || responseFamily === 'catalog'
+            ? 'summary'
+            : 'standard');
+    return {
+        action,
+        publicTool,
+        aliases: overrides.aliases ?? [],
+        authRequirement: overrides.authRequirement ?? 'apiKey',
+        capabilityGate: overrides.capabilityGate ?? gate('agent', 'Available on every plan'),
+        mutability: overrides.mutability ?? (publicTool === 'heliusWrite' ? 'write' : 'read'),
+        responseFamily,
+        defaultDetail,
+        handleEligibility: overrides.handleEligibility ?? !['scalar', 'mutationReceipt'].includes(responseFamily),
+        normalizer: overrides.normalizer ?? responseFamily,
+        continuationModel: overrides.continuationModel ?? 'none',
+    };
+}
+function addEntries(target, actions, overrides = {}) {
+    for (const action of actions) {
+        target[action] = makeEntry(action, overrides);
+    }
+}
+const catalog = {};
+addEntries(catalog, HELIUS_ACCOUNT_ACTIONS, {
+    authRequirement: 'none',
+    capabilityGate: gate('agent', 'Account setup and plan metadata'),
+    responseFamily: 'record',
+});
+addEntries(catalog, HELIUS_WALLET_ACTIONS, {
+    capabilityGate: gate('agent', 'Wallet data'),
+    responseFamily: 'record',
+});
+addEntries(catalog, HELIUS_ASSET_ACTIONS, {
+    capabilityGate: gate('agent', 'Asset and DAS queries'),
+    responseFamily: 'record',
+});
+addEntries(catalog, HELIUS_TRANSACTION_ACTIONS, {
+    capabilityGate: gate('agent', 'Transaction parsing and history'),
+    responseFamily: 'history',
+});
+addEntries(catalog, HELIUS_CHAIN_ACTIONS, {
+    capabilityGate: gate('agent', 'Core chain state'),
+    responseFamily: 'record',
+});
+addEntries(catalog, HELIUS_STREAMING_ACTIONS, {
+    capabilityGate: gate('agent', 'Streaming and webhook operations'),
+    responseFamily: 'record',
+});
+addEntries(catalog, HELIUS_KNOWLEDGE_ACTIONS, {
+    authRequirement: 'none',
+    capabilityGate: gate('agent', 'Documentation and knowledge'),
+    responseFamily: 'document',
+});
+addEntries(catalog, HELIUS_WRITE_ACTIONS, {
+    authRequirement: 'signer',
+    capabilityGate: gate('agent', 'Transaction sending and staking'),
+    mutability: 'write',
+    responseFamily: 'mutationReceipt',
+});
+addEntries(catalog, HELIUS_COMPRESSION_ACTIONS, {
+    capabilityGate: gate('agent', 'Compression state queries'),
+    responseFamily: 'record',
+});
+const developerWalletGate = gate('developer', 'Developer plan or higher');
+const businessStreamingGate = gate('business', 'Business plan or higher');
+const professionalLaserstreamGate = gate('developer', 'Developer plan on devnet', [
+    {
+        id: 'professional:laserstream-mainnet',
+        minimumPlan: 'professional',
+        predicate: { kind: 'network', oneOf: ['mainnet-beta'] },
+        label: 'Professional plan on mainnet',
+    },
+]);
+const scalarActions = [
+    'getBalance',
+    'getAccountPlan',
+    'getNetworkStatus',
+    'getPriorityFeeEstimate',
+    'getCompressedBalance',
+    'getCompressedBalanceByOwner',
+    'getCompressedTokenAccountBalance',
+    'getIndexerHealth',
+    'getIndexerSlot',
+    'getWithdrawableAmount',
+];
+for (const action of scalarActions) {
+    catalog[action] = makeEntry(action, {
+        ...catalog[action],
+        responseFamily: 'scalar',
+        defaultDetail: 'full',
+        handleEligibility: false,
+    });
+}
+const mutationActions = [
+    'createWebhook',
+    'updateWebhook',
+    'deleteWebhook',
+    'transferSol',
+    'transferToken',
+    'stakeSOL',
+    'unstakeSOL',
+    'withdrawStake',
+];
+for (const action of mutationActions) {
+    catalog[action] = makeEntry(action, {
+        ...catalog[action],
+        responseFamily: 'mutationReceipt',
+        defaultDetail: 'full',
+        handleEligibility: false,
+    });
+}
+const listActions = [
+    'getTokenBalances',
+    'getWalletBalances',
+    'getWalletHistory',
+    'getWalletTransfers',
+    'batchWalletIdentity',
+    'getAssetsByOwner',
+    'searchAssets',
+    'getAssetsByGroup',
+    'getNftEditions',
+    'getTokenHolders',
+    'getTokenAccounts',
+    'getProgramAccounts',
+    'getStakeAccounts',
+    'getAllWebhooks',
+    'listHeliusDocTopics',
+    'listSIMDs',
+    'getCompressedAccountsByOwner',
+    'getMultipleCompressedAccounts',
+    'getCompressedMintTokenHolders',
+    'getCompressedTokenAccountsByOwner',
+    'getCompressedTokenAccountsByDelegate',
+    'getCompressedTokenBalancesByOwnerV2',
+];
+for (const action of listActions) {
+    catalog[action] = makeEntry(action, {
+        ...catalog[action],
+        responseFamily: 'list',
+        defaultDetail: 'standard',
+    });
+}
+const historyActions = [
+    'parseTransactions',
+    'getTransactionHistory',
+    'getSignaturesForAsset',
+    'getCompressionSignaturesForAccount',
+    'getCompressionSignaturesForAddress',
+    'getCompressionSignaturesForOwner',
+    'getCompressionSignaturesForTokenOwner',
+    'getLatestCompressionSignatures',
+    'getLatestNonVotingSignatures',
+];
+for (const action of historyActions) {
+    catalog[action] = makeEntry(action, {
+        ...catalog[action],
+        responseFamily: 'history',
+        defaultDetail: 'standard',
+    });
+}
+const documentActions = [
+    'lookupHeliusDocs',
+    'getHeliusCreditsInfo',
+    'getRateLimitInfo',
+    'getSIMD',
+    'searchSolanaDocs',
+    'readSolanaSourceFile',
+    'fetchHeliusBlog',
+    'getSenderInfo',
+    'getWebhookGuide',
+    'getLatencyComparison',
+    'getEnhancedWebSocketInfo',
+    'getLaserstreamInfo',
+    'getPumpFunGuide',
+];
+for (const action of documentActions) {
+    catalog[action] = makeEntry(action, {
+        ...catalog[action],
+        responseFamily: 'document',
+        defaultDetail: 'summary',
+    });
+}
+catalog.recommendStack = makeEntry('recommendStack', {
+    responseFamily: 'catalog',
+    defaultDetail: 'summary',
+});
+for (const action of ['transactionSubscribe', 'accountSubscribe', 'laserstreamSubscribe']) {
+    catalog[action] = makeEntry(action, {
+        ...catalog[action],
+        responseFamily: 'streamingConfig',
+        defaultDetail: 'summary',
+    });
+}
+catalog.setHeliusApiKey = makeEntry('setHeliusApiKey', {
+    authRequirement: 'none',
+    capabilityGate: gate('agent', 'API key configuration'),
+    responseFamily: 'record',
+    defaultDetail: 'standard',
+    handleEligibility: false,
+});
+catalog.generateKeypair = makeEntry('generateKeypair', {
+    authRequirement: 'none',
+    capabilityGate: gate('agent', 'Local keypair generation'),
+    responseFamily: 'record',
+    defaultDetail: 'standard',
+    handleEligibility: false,
+});
+catalog.getStarted = makeEntry('getStarted', {
+    authRequirement: 'none',
+    capabilityGate: gate('agent', 'Setup instructions'),
+    responseFamily: 'record',
+    defaultDetail: 'standard',
+    handleEligibility: false,
+});
+catalog.signup = makeEntry('signup', {
+    authRequirement: 'signer',
+    capabilityGate: gate('agent', 'Signup flow'),
+    responseFamily: 'record',
+    defaultDetail: 'standard',
+    handleEligibility: false,
+});
+catalog.purchaseCredits = makeEntry('purchaseCredits', {
+    authRequirement: 'jwt',
+    capabilityGate: gate('agent', 'Prepaid credits top-up'),
+    responseFamily: 'record',
+    defaultDetail: 'standard',
+    handleEligibility: false,
+});
+catalog.getAccountStatus = makeEntry('getAccountStatus', {
+    authRequirement: 'jwt',
+    capabilityGate: gate('agent', 'Authenticated account status'),
+    responseFamily: 'record',
+});
+catalog.previewUpgrade = makeEntry('previewUpgrade', {
+    authRequirement: 'jwt',
+    capabilityGate: gate('agent', 'Upgrade preview'),
+    responseFamily: 'record',
+    handleEligibility: false,
+});
+catalog.upgradePlan = makeEntry('upgradePlan', {
+    authRequirement: 'jwtAndSigner',
+    capabilityGate: gate('agent', 'Upgrade checkout'),
+    mutability: 'write',
+    responseFamily: 'mutationReceipt',
+    handleEligibility: false,
+});
+catalog.payRenewal = makeEntry('payRenewal', {
+    authRequirement: 'jwtAndSigner',
+    capabilityGate: gate('agent', 'Renewal checkout'),
+    mutability: 'write',
+    responseFamily: 'mutationReceipt',
+    handleEligibility: false,
+});
+catalog.compareHeliusPlans = makeEntry('compareHeliusPlans', {
+    authRequirement: 'none',
+    capabilityGate: gate('agent', 'Plan comparison'),
+    responseFamily: 'catalog',
+    defaultDetail: 'summary',
+});
+catalog.getHeliusPlanInfo = makeEntry('getHeliusPlanInfo', {
+    authRequirement: 'none',
+    capabilityGate: gate('agent', 'Plan details'),
+    responseFamily: 'catalog',
+    defaultDetail: 'summary',
+});
+catalog.getWalletBalances = makeEntry('getWalletBalances', {
+    capabilityGate: developerWalletGate,
+    responseFamily: 'list',
+    defaultDetail: 'standard',
+});
+catalog.getWalletBalanceAt = makeEntry('getWalletBalanceAt', {
+    capabilityGate: developerWalletGate,
+    responseFamily: 'record',
+    defaultDetail: 'standard',
+    handleEligibility: false,
+});
+catalog.getWalletHistory = makeEntry('getWalletHistory', {
+    capabilityGate: developerWalletGate,
+    responseFamily: 'history',
+    defaultDetail: 'standard',
+});
+catalog.getWalletTransfers = makeEntry('getWalletTransfers', {
+    capabilityGate: developerWalletGate,
+    responseFamily: 'history',
+    defaultDetail: 'standard',
+});
+catalog.getWalletIdentity = makeEntry('getWalletIdentity', {
+    capabilityGate: developerWalletGate,
+    responseFamily: 'record',
+    defaultDetail: 'standard',
+    handleEligibility: false,
+});
+catalog.batchWalletIdentity = makeEntry('batchWalletIdentity', {
+    capabilityGate: developerWalletGate,
+    responseFamily: 'list',
+    defaultDetail: 'standard',
+});
+catalog.getWalletFundedBy = makeEntry('getWalletFundedBy', {
+    capabilityGate: developerWalletGate,
+    responseFamily: 'record',
+    defaultDetail: 'standard',
+    handleEligibility: false,
+});
+catalog.transactionSubscribe = makeEntry('transactionSubscribe', {
+    capabilityGate: businessStreamingGate,
+    responseFamily: 'streamingConfig',
+    defaultDetail: 'summary',
+});
+catalog.accountSubscribe = makeEntry('accountSubscribe', {
+    capabilityGate: businessStreamingGate,
+    responseFamily: 'streamingConfig',
+    defaultDetail: 'summary',
+});
+catalog.laserstreamSubscribe = makeEntry('laserstreamSubscribe', {
+    capabilityGate: professionalLaserstreamGate,
+    responseFamily: 'streamingConfig',
+    defaultDetail: 'summary',
+});
+catalog.getEnhancedWebSocketInfo = makeEntry('getEnhancedWebSocketInfo', {
+    authRequirement: 'none',
+    capabilityGate: gate('agent', 'Enhanced WebSocket info', [
+        {
+            id: 'business:enhanced-websockets',
+            minimumPlan: 'business',
+            predicate: always,
+            label: 'Enhanced WebSockets require Business plan or higher',
+        },
+    ]),
+    responseFamily: 'document',
+    defaultDetail: 'summary',
+});
+catalog.getLaserstreamInfo = makeEntry('getLaserstreamInfo', {
+    authRequirement: 'none',
+    capabilityGate: gate('agent', 'Laserstream info', [
+        {
+            id: 'developer:laserstream-devnet',
+            minimumPlan: 'developer',
+            predicate: { kind: 'network', oneOf: ['devnet'] },
+            label: 'Laserstream on devnet requires Developer plan or higher',
+        },
+        {
+            id: 'professional:laserstream-mainnet-info',
+            minimumPlan: 'professional',
+            predicate: { kind: 'network', oneOf: ['mainnet-beta'] },
+            label: 'Laserstream on mainnet requires Professional plan',
+        },
+    ]),
+    responseFamily: 'document',
+    defaultDetail: 'summary',
+});
+catalog.getTransactionHistory = makeEntry('getTransactionHistory', {
+    responseFamily: 'history',
+    defaultDetail: 'standard',
+    continuationModel: 'transactionHistory',
+});
+catalog.getTransfersByAddress = makeEntry('getTransfersByAddress', {
+    responseFamily: 'history',
+    defaultDetail: 'standard',
+    continuationModel: 'transactionHistory',
+});
+for (const action of ACTION_NAMES) {
+    if (!catalog[action]) {
+        throw new Error(`Missing action catalog entry for ${action}`);
+    }
+}
+export const ACTION_CATALOG = catalog;
+export function getActionCatalogEntry(action) {
+    return ACTION_CATALOG[action];
+}
+export function getActionsForTool(tool) {
+    return (Object.values(ACTION_CATALOG)
+        .filter((entry) => entry.publicTool === tool)
+        .map((entry) => entry.action)
+        .sort());
+}

package/dist/router/context.d.ts

@@ -0,0 +1,5 @@
+export type RouterContext = {
+    sessionKey: string;
+    network: 'mainnet-beta' | 'devnet';
+};
+export declare function getRouterContext(): RouterContext;

package/dist/router/context.js

@@ -0,0 +1,10 @@
+import { randomUUID } from 'node:crypto';
+import { getNetwork } from '../utils/helius.js';
+const SESSION_KEY = randomUUID();
+export function getRouterContext() {
+    const network = getNetwork();
+    return {
+        sessionKey: SESSION_KEY,
+        network: network === 'devnet' ? 'devnet' : 'mainnet-beta',
+    };
+}

package/dist/router/dispatch.d.ts

@@ -0,0 +1,4 @@
+import type { RoutedPublicToolName } from './action-groups.js';
+import { type RouterResponse } from './responses.js';
+export declare function dispatchRoutedTool(publicTool: RoutedPublicToolName, params: Record<string, unknown>, extra: unknown): Promise<RouterResponse>;
+export declare function expandStoredResult(params: Record<string, unknown>, extra: unknown): Promise<RouterResponse>;

package/dist/router/dispatch.js

@@ -0,0 +1,276 @@
+import { getStoredResult, putStoredResult } from '../results/store.js';
+import { callActionHandler } from './action-handlers.js';
+import { getActionCatalogEntry } from './catalog.js';
+import { getRouterContext } from './context.js';
+import { ACTION_REQUIRED_PARAMS } from './required-params.js';
+import { applyItemSelection, applyRangeSelection, applySectionSelection, buildTextVariant, collectSectionHints, compactErrorText, estimateRenderedSize, getFamilyLimit, mcpErrorCompact, mcpResultHandle, mcpText, toPlainText, } from './responses.js';
+function isHandleEligible(entry) {
+    return entry.handleEligibility;
+}
+function pickRequestedDetail(entry, detail) {
+    if (detail === 'summary' || detail === 'standard' || detail === 'full') {
+        return detail;
+    }
+    return entry.defaultDetail;
+}
+function buildActionParams(input) {
+    const { action: _action, detail: _detail, args, ...topLevel } = input;
+    const merged = {
+        ...(args && typeof args === 'object' && !Array.isArray(args) ? args : {}),
+    };
+    for (const [key, value] of Object.entries(topLevel)) {
+        if (value !== undefined) {
+            merged[key] = value;
+        }
+    }
+    // Normalize common address field mismatches
+    if (!merged.address && merged.ownerAddress)
+        merged.address = merged.ownerAddress;
+    if (!merged.owner && merged.address && !merged.ownerAddress)
+        merged.owner = merged.address;
+    if (!merged.address && merged.owner)
+        merged.address = merged.owner;
+    return merged;
+}
+function detectContinuation(action, params, text) {
+    if (action === 'getTransactionHistory') {
+        // Fragile: depends on handler markdown format "**Next Page Token:** `<token>`"
+        const tokenMatch = text.match(/\*\*Next Page Token:\*\*\s+`([^`]+)`/);
+        if (tokenMatch) {
+            const mode = typeof params.mode === 'string' ? params.mode : 'parsed';
+            const next = mode === 'raw'
+                ? { kind: 'rawApi', paginationToken: tokenMatch[1] }
+                : { kind: 'historyApi', paginationToken: tokenMatch[1] };
+            return { model: 'transactionHistory', next };
+        }
+        const hasFilters = [
+            'paginationToken',
+            'status',
+            'tokenAccounts',
+            'blockTimeGte',
+            'blockTimeLte',
+            'slotGte',
+            'slotLte',
+        ].some((key) => params[key] !== undefined);
+        const mode = typeof params.mode === 'string' ? params.mode : 'parsed';
+        const sortOrder = typeof params.sortOrder === 'string' ? params.sortOrder : 'desc';
+        if (mode === 'signatures' && sortOrder === 'desc' && !hasFilters) {
+            // Fragile: depends on handler "✅/❌ <base58sig>" line format for signature extraction
+            const signatures = Array.from(text.matchAll(/^[^\S\r\n]*[✅❌]\s+([1-9A-HJ-NP-Za-km-z]{86,88})$/gm)).map((match) => match[1]);
+            const lastSignature = signatures.at(-1);
+            if (lastSignature) {
+                return {
+                    model: 'transactionHistory',
+                    next: {
+                        kind: 'signaturesQuick',
+                        nextBefore: lastSignature,
+                        lastSeenSignature: lastSignature,
+                        until: typeof params.until === 'string' ? params.until : undefined,
+                    },
+                };
+            }
+        }
+    }
+    if (action === 'getTransfersByAddress') {
+        // Fragile: depends on handler markdown format "**Next Page Token:** `<token>`" (mirrors getTransactionHistory)
+        const tokenMatch = text.match(/\*\*Next Page Token:\*\*\s+`([^`]+)`/);
+        if (tokenMatch) {
+            return {
+                model: 'transactionHistory',
+                next: { kind: 'rawApi', paginationToken: tokenMatch[1] },
+            };
+        }
+    }
+    if (typeof params.page === 'number') {
+        return { model: 'page', nextPage: params.page + 1 };
+    }
+    return { model: 'none' };
+}
+function buildAvailableExpansions(family, continuation, sectionHints) {
+    const expansions = new Set(['full']);
+    if (family === 'document' || sectionHints.length > 0) {
+        expansions.add('section');
+        expansions.add('range');
+    }
+    if (family === 'list' || family === 'history') {
+        expansions.add('item');
+    }
+    if (continuation.model === 'page') {
+        expansions.add('page');
+    }
+    if (continuation.model === 'transactionHistory' && continuation.next) {
+        expansions.add('continuation');
+    }
+    return Array.from(expansions);
+}
+function buildStoredResult(entry, publicTool, params, summary, text) {
+    const context = getRouterContext();
+    const continuation = detectContinuation(entry.action, params, text);
+    const sectionHints = collectSectionHints(text);
+    const stored = putStoredResult({
+        kind: entry.responseFamily,
+        ownerSessionKey: context.sessionKey,
+        summary,
+        availableExpansions: buildAvailableExpansions(entry.responseFamily, continuation, sectionHints),
+        payload: {
+            recipe: {
+                publicTool,
+                action: entry.action,
+                params,
+                responseFamily: entry.responseFamily,
+                defaultDetail: entry.defaultDetail,
+            },
+            continuation,
+            sectionHints,
+        },
+    });
+    return stored;
+}
+function normalizeSuccessResponse(entry, publicTool, params, text, requestedDetail, allowHandles) {
+    const baseText = text.trim();
+    const summaryText = buildTextVariant(entry.responseFamily, 'summary', baseText);
+    const standardText = buildTextVariant(entry.responseFamily, 'standard', baseText);
+    const fullText = buildTextVariant(entry.responseFamily, 'full', baseText);
+    const requestedText = requestedDetail === 'summary'
+        ? summaryText
+        : requestedDetail === 'standard'
+            ? standardText
+            : fullText;
+    const size = estimateRenderedSize(requestedText);
+    const limit = getFamilyLimit(entry.responseFamily, requestedDetail);
+    const needsHandle = allowHandles
+        && isHandleEligible(entry)
+        && (requestedDetail === 'summary' || size > limit);
+    if (needsHandle) {
+        const stored = buildStoredResult(entry, publicTool, params, summaryText, fullText);
+        return mcpResultHandle(summaryText, stored.resultId, stored.availableExpansions, {
+            family: entry.responseFamily,
+            action: entry.action,
+            defaultDetail: entry.defaultDetail,
+        });
+    }
+    return mcpText(requestedText, {
+        family: entry.responseFamily,
+        action: entry.action,
+        detail: requestedDetail,
+    });
+}
+function normalizeActionResponse(entry, publicTool, params, result, requestedDetail, allowHandles) {
+    const text = toPlainText(result);
+    if (result.isError) {
+        return mcpErrorCompact(compactErrorText(text), {
+            action: entry.action,
+            publicTool,
+            error: true,
+        });
+    }
+    return normalizeSuccessResponse(entry, publicTool, params, text, requestedDetail, allowHandles);
+}
+async function executeActionViaRouter(publicTool, action, params, requestedDetail, extra, allowHandles) {
+    const entry = getActionCatalogEntry(action);
+    try {
+        const result = await callActionHandler(action, params, extra);
+        return normalizeActionResponse(entry, publicTool, params, result, requestedDetail, allowHandles);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return mcpErrorCompact(message, { code: 'HANDLER_ERROR', action, publicTool });
+    }
+}
+export async function dispatchRoutedTool(publicTool, params, extra) {
+    const action = params.action;
+    if (!action) {
+        return mcpErrorCompact('Missing required "action" field.', { code: 'MISSING_ACTION' });
+    }
+    const requestedDetail = pickRequestedDetail(getActionCatalogEntry(action), params.detail);
+    const actionParams = buildActionParams(params);
+    const requiredFields = ACTION_REQUIRED_PARAMS[action];
+    if (requiredFields) {
+        const missing = requiredFields.filter((f) => actionParams[f] === undefined);
+        if (missing.length > 0) {
+            return mcpErrorCompact(`Missing required parameter${missing.length > 1 ? 's' : ''} for ${action}: ${missing.join(', ')}`, { code: 'MISSING_PARAMS', action, missing });
+        }
+    }
+    return executeActionViaRouter(publicTool, action, actionParams, requestedDetail, extra, true);
+}
+function applyContinuation(params, stored, continuation) {
+    if (!continuation) {
+        return params;
+    }
+    if (continuation !== 'next') {
+        return {
+            ...params,
+            continuation,
+        };
+    }
+    if (stored.payload.continuation.model === 'transactionHistory' && stored.payload.continuation.next) {
+        const next = stored.payload.continuation.next;
+        if (next.kind === 'signaturesQuick') {
+            return {
+                ...params,
+                before: next.nextBefore,
+            };
+        }
+        return {
+            ...params,
+            paginationToken: next.paginationToken,
+        };
+    }
+    if (stored.payload.continuation.model === 'page' && stored.payload.continuation.nextPage !== undefined) {
+        return {
+            ...params,
+            page: stored.payload.continuation.nextPage,
+        };
+    }
+    return params;
+}
+export async function expandStoredResult(params, extra) {
+    const resultId = typeof params.resultId === 'string' ? params.resultId : '';
+    if (!resultId) {
+        return mcpErrorCompact('Missing required "resultId".', { code: 'MISSING_RESULT_ID' });
+    }
+    const context = getRouterContext();
+    const stored = getStoredResult(resultId, context.sessionKey);
+    if (!stored) {
+        return mcpErrorCompact('Result handle not found or no longer available. Re-run the original action.', {
+            code: 'RESULT_NOT_FOUND',
+            resultId,
+        });
+    }
+    let nextParams = {
+        ...stored.payload.recipe.params,
+    };
+    if (typeof params.page === 'number') {
+        nextParams.page = params.page;
+    }
+    nextParams = applyContinuation(nextParams, stored, typeof params.continuation === 'string' ? params.continuation : undefined);
+    const requestedDetail = (params.detail === 'summary' || params.detail === 'standard' || params.detail === 'full')
+        ? params.detail
+        : 'full';
+    try {
+        const rawResponse = await callActionHandler(stored.payload.recipe.action, nextParams, extra);
+        const rawText = toPlainText(rawResponse);
+        if (rawResponse.isError) {
+            return mcpErrorCompact(compactErrorText(rawText), {
+                code: 'EXPAND_FAILED',
+                action: stored.payload.recipe.action,
+            });
+        }
+        const selected = applyRangeSelection(applyItemSelection(applySectionSelection(rawText, typeof params.section === 'string' ? params.section : undefined), typeof params.item === 'number' ? params.item : undefined), typeof params.range === 'string' ? params.range : undefined);
+        const entry = getActionCatalogEntry(stored.payload.recipe.action);
+        if (params.continuation === 'next' || typeof params.page === 'number') {
+            return normalizeSuccessResponse(entry, stored.payload.recipe.publicTool, nextParams, selected, requestedDetail, true);
+        }
+        const rendered = buildTextVariant(entry.responseFamily, requestedDetail, selected);
+        return mcpText(rendered, {
+            action: stored.payload.recipe.action,
+            family: stored.kind,
+            resultId,
+            detail: requestedDetail,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return mcpErrorCompact(message, { code: 'EXPAND_HANDLER_ERROR', action: stored.payload.recipe.action });
+    }
+}