@viral_vector/ig-mcp 0.1.0

package/dist/mcp/tools.js

@@ -0,0 +1,1466 @@
+import { z } from 'zod';
+import { BRIDGE_ERROR_CODES, CAPABILITIES } from '../bridge/protocol.js';
+const MEDIA_SOURCE_VALUES = ['posts', 'reels', 'stories', 'highlights'];
+const REFRESH_DATA_VALUES = ['profile', 'followers', 'following', 'media'];
+const AUDIENCE_KIND_VALUES = ['followers', 'following'];
+const LIBRARY_INCLUDE_VALUES = ['summary', 'accounts', 'hashtags'];
+const ACCOUNT_INCLUDE_VALUES = [
+    'profile_snapshot',
+    'engagement_snapshot',
+    'audience_summary',
+    'media_summary',
+    'recent_media',
+    'exports',
+    'actions'
+];
+const HASHTAG_INCLUDE_VALUES = [
+    'snapshot',
+    'media_summary',
+    'recent_media',
+    'creators',
+    'related',
+    'exports',
+    'actions'
+];
+const MEDIA_INCLUDE_VALUES = ['download_status'];
+const OPERATION_KIND_VALUES = [
+    'account_track',
+    'account_update_role',
+    'account_untrack',
+    'account_refresh',
+    'hashtag_track',
+    'hashtag_untrack',
+    'hashtag_refresh',
+    'media_comments_refresh',
+    'media_download',
+    'export_create'
+];
+const OPERATION_STATUS_VALUES = ['queued', 'running', 'completed', 'failed', 'cancelled'];
+const baseStatusSchema = z.object({
+    connected: z.boolean(),
+    clientId: z.string().nullable().optional(),
+    extensionVersion: z.string().nullable().optional(),
+    connectedAt: z.string().nullable().optional(),
+    lastSeenAt: z.string().nullable().optional()
+});
+const includeSchema = z.array(z.enum(['exports', 'actions'])).optional();
+const readOnlyAnnotations = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+};
+const liveReadOnlyAnnotations = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+};
+const operationAnnotations = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+};
+export const V2_TOOL_DEFINITIONS = [
+    {
+        name: 'vv_status',
+        title: 'Viral Vector Status',
+        description: 'Returns local bridge and Instagram session status for the ViralVector Instagram library.',
+        inputSchema: {},
+        annotations: readOnlyAnnotations,
+        handler: async (_input, registry) => {
+            const connection = registry.getStatus();
+            const session = await requestCapability(registry, CAPABILITIES.SOCIAL_SESSION_STATUS, {});
+            if (!session.ok) {
+                return errorToolResponse(session);
+            }
+            return jsonToolResponse({
+                bridge: summarizeConnection(connection),
+                session: session.data
+            });
+        }
+    },
+    {
+        name: 'vv_library_query',
+        title: 'Viral Vector Library Query',
+        description: 'Queries locally saved Instagram accounts and hashtags, with optional library summary.',
+        inputSchema: {
+            query: z.string().optional(),
+            include: z.array(z.enum(LIBRARY_INCLUDE_VALUES)).optional(),
+            limit: z.number().int().nonnegative().optional(),
+            offset: z.number().int().nonnegative().optional()
+        },
+        annotations: readOnlyAnnotations,
+        handler: async (input, registry) => {
+            const response = await requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_LIST_ACCOUNTS, {});
+            if (!response.ok) {
+                return errorToolResponse(response);
+            }
+            const value = asObject(response.data);
+            const query = stringOrNull(input.query)?.toLowerCase() ?? '';
+            const include = asStringArray(input.include);
+            const includeAccounts = include.length === 0 || include.includes('accounts');
+            const includeHashtags = include.length === 0 || include.includes('hashtags');
+            const includeSummary = include.length === 0 || include.includes('summary');
+            const accounts = includeAccounts
+                ? paginate(asArray(value.accounts).filter((item) => !query || matchesSearch(item, query)).map(summarizeAccount), input)
+                : [];
+            const hashtags = includeHashtags
+                ? paginate(asArray(value.hashtags).filter((item) => !query || matchesSearch(item, query)).map(summarizeHashtag), input)
+                : [];
+            return jsonToolResponse(queryEnvelope(input, {
+                results: {
+                    accounts,
+                    hashtags
+                },
+                included: {
+                    summary: includeSummary ? {
+                        accounts: asArray(value.accounts).length,
+                        hashtags: asArray(value.hashtags).length,
+                        profileSnapshots: asArray(value.profileSnapshots).length,
+                        hashtagSnapshots: asArray(value.hashtagSnapshots).length
+                    } : undefined
+                }
+            }));
+        }
+    },
+    {
+        name: 'vv_account_query',
+        title: 'Viral Vector Account Query',
+        description: 'Queries saved Instagram accounts or returns account context with optional snapshots, summaries, recent media, exports, and actions.',
+        inputSchema: {
+            username: z.string().min(1).optional(),
+            query: z.string().optional(),
+            role: z.enum(['my_account', 'competitor', 'benchmark', 'creator', 'uncategorized']).optional(),
+            include: z.array(z.enum(ACCOUNT_INCLUDE_VALUES)).optional(),
+            mediaLimit: z.number().int().nonnegative().optional(),
+            limit: z.number().int().nonnegative().optional(),
+            offset: z.number().int().nonnegative().optional()
+        },
+        annotations: readOnlyAnnotations,
+        handler: async (input, registry) => {
+            if (typeof input.username === 'string' && input.username.trim()) {
+                const detail = await requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_GET_ACCOUNT_DETAIL, {
+                    username: input.username,
+                    postsLimit: input.mediaLimit
+                });
+                if (!detail.ok) {
+                    return errorToolResponse(detail);
+                }
+                const exportsResult = includesV2(input, 'exports')
+                    ? await requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_LIST_EXPORTS, {
+                        targetType: 'account',
+                        targetHandle: input.username
+                    })
+                    : null;
+                if (exportsResult && !exportsResult.ok) {
+                    return errorToolResponse(exportsResult);
+                }
+                return jsonToolResponse(queryEnvelope(input, {
+                    item: buildAccountQueryItem(asObject(detail.data), input, exportsResult?.data)
+                }));
+            }
+            const response = await requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_LIST_ACCOUNTS, {});
+            if (!response.ok) {
+                return errorToolResponse(response);
+            }
+            const query = stringOrNull(input.query)?.toLowerCase() ?? '';
+            const role = typeof input.role === 'string' ? input.role : null;
+            const accounts = asArray(asObject(response.data).accounts)
+                .map(asObject)
+                .filter((item) => !role || String(item.targetRole ?? 'uncategorized') === role)
+                .filter((item) => !query || matchesSearch(item, query))
+                .map(summarizeAccount);
+            return jsonToolResponse(queryEnvelope(input, {
+                results: {
+                    accounts: paginate(accounts, input)
+                }
+            }));
+        }
+    },
+    {
+        name: 'vv_account_audience_query',
+        title: 'Viral Vector Account Audience Query',
+        description: 'Queries saved followers or following records for an Instagram account.',
+        inputSchema: {
+            username: z.string().min(1),
+            kind: z.enum(AUDIENCE_KIND_VALUES),
+            query: z.string().optional(),
+            privacy: z.enum(['public', 'private', 'unknown']).optional(),
+            verification: z.enum(['verified', 'unverified', 'unknown']).optional(),
+            limit: z.number().int().nonnegative().optional(),
+            offset: z.number().int().nonnegative().optional()
+        },
+        annotations: readOnlyAnnotations,
+        handler: async (input, registry) => queryAudience(input, registry)
+    },
+    {
+        name: 'vv_hashtag_query',
+        title: 'Viral Vector Hashtag Query',
+        description: 'Queries saved Instagram hashtags or returns hashtag context with optional snapshot, media, creators, related hashtags, exports, and actions.',
+        inputSchema: {
+            handle: z.string().min(1).optional(),
+            query: z.string().optional(),
+            include: z.array(z.enum(HASHTAG_INCLUDE_VALUES)).optional(),
+            mediaLimit: z.number().int().nonnegative().optional(),
+            limit: z.number().int().nonnegative().optional(),
+            offset: z.number().int().nonnegative().optional()
+        },
+        annotations: readOnlyAnnotations,
+        handler: async (input, registry) => {
+            if (typeof input.handle === 'string' && input.handle.trim()) {
+                const detail = await requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_GET_HASHTAG_DETAIL, {
+                    handle: input.handle,
+                    postsLimit: input.mediaLimit
+                });
+                if (!detail.ok) {
+                    return errorToolResponse(detail);
+                }
+                const exportsResult = includesV2(input, 'exports')
+                    ? await requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_LIST_EXPORTS, {
+                        targetType: 'hashtag',
+                        targetHandle: input.handle
+                    })
+                    : null;
+                if (exportsResult && !exportsResult.ok) {
+                    return errorToolResponse(exportsResult);
+                }
+                return jsonToolResponse(queryEnvelope(input, {
+                    item: buildHashtagQueryItem(asObject(detail.data), input, exportsResult?.data)
+                }));
+            }
+            const response = await requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_LIST_ACCOUNTS, {});
+            if (!response.ok) {
+                return errorToolResponse(response);
+            }
+            const query = stringOrNull(input.query)?.toLowerCase() ?? '';
+            const hashtags = asArray(asObject(response.data).hashtags)
+                .filter((item) => !query || matchesSearch(item, query))
+                .map(summarizeHashtag);
+            return jsonToolResponse(queryEnvelope(input, {
+                results: {
+                    hashtags: paginate(hashtags, input)
+                }
+            }));
+        }
+    },
+    {
+        name: 'vv_media_query',
+        title: 'Viral Vector Media Query',
+        description: 'Queries saved account or hashtag media, or returns a single media item by media id or shortcode.',
+        inputSchema: {
+            account: z.string().min(1).optional(),
+            hashtag: z.string().min(1).optional(),
+            mediaId: z.string().min(1).optional(),
+            shortcode: z.string().min(1).optional(),
+            sources: z.array(z.enum(MEDIA_SOURCE_VALUES)).optional(),
+            include: z.array(z.enum(MEDIA_INCLUDE_VALUES)).optional(),
+            limit: z.number().int().nonnegative().optional(),
+            offset: z.number().int().nonnegative().optional()
+        },
+        annotations: readOnlyAnnotations,
+        handler: async (input, registry) => queryMedia(input, registry)
+    },
+    {
+        name: 'vv_comments_query',
+        title: 'Viral Vector Comments Query',
+        description: 'Queries saved comments for a media item by Instagram shortcode.',
+        inputSchema: {
+            shortcode: z.string().min(1),
+            limit: z.number().int().nonnegative().optional(),
+            offset: z.number().int().nonnegative().optional()
+        },
+        annotations: readOnlyAnnotations,
+        handler: async (input, registry) => {
+            const response = await requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_GET_POST_DETAIL, {
+                shortcode: input.shortcode,
+                commentsLimit: input.limit
+            });
+            if (!response.ok) {
+                return errorToolResponse(response);
+            }
+            const value = asObject(response.data);
+            return jsonToolResponse(queryEnvelope(input, {
+                item: summarizeMediaFromPost(value.post),
+                results: {
+                    comments: paginate(asArray(value.comments), input)
+                }
+            }));
+        }
+    },
+    {
+        name: 'vv_operation_run',
+        title: 'Viral Vector Operation Run',
+        description: 'Runs or dry-runs local library mutations, refreshes, downloads, and exports. Untrack operations delete local tracked targets only; they do not delete Instagram content.',
+        inputSchema: {
+            kind: z.enum(OPERATION_KIND_VALUES),
+            input: z.record(z.string(), z.unknown()),
+            dryRun: z.boolean().optional(),
+            idempotencyKey: z.string().optional()
+        },
+        annotations: operationAnnotations,
+        handler: async (input, registry) => runOperation(input, registry)
+    },
+    {
+        name: 'vv_operation_query',
+        title: 'Viral Vector Operation Query',
+        description: 'Queries collection operation status and recent operation history.',
+        inputSchema: {
+            operationId: z.string().min(1).optional(),
+            kind: z.string().optional(),
+            status: z.enum(OPERATION_STATUS_VALUES).optional(),
+            account: z.string().min(1).optional(),
+            hashtag: z.string().min(1).optional(),
+            shortcode: z.string().min(1).optional(),
+            limit: z.number().int().nonnegative().optional(),
+            offset: z.number().int().nonnegative().optional()
+        },
+        annotations: readOnlyAnnotations,
+        handler: async (input, registry) => queryOperations(input, registry)
+    },
+    {
+        name: 'ig_search',
+        title: 'Instagram Live Search',
+        description: 'Temporarily searches Instagram live candidates for accounts or hashtags. Results are not saved or tracked; use vv_operation_run to persist a chosen candidate.',
+        inputSchema: {
+            query: z.string().min(1),
+            targets: z.array(z.enum(['accounts', 'hashtags'])).min(1).optional(),
+            limit: z.number().int().min(1).max(20).optional()
+        },
+        annotations: liveReadOnlyAnnotations,
+        handler: async (input, registry) => searchInstagram(input, registry)
+    },
+    {
+        name: 'ig_lookup',
+        title: 'Instagram Live Lookup',
+        description: 'Temporarily looks up one Instagram account or hashtag with optional recent media and related hashtag context. Results are not saved or tracked.',
+        inputSchema: {
+            type: z.enum(['account', 'hashtag']),
+            username: z.string().min(1).optional(),
+            hashtag: z.string().min(1).optional(),
+            include: z.array(z.enum(['recent_media', 'related'])).optional(),
+            mediaLimit: z.number().int().min(1).max(20).optional()
+        },
+        annotations: liveReadOnlyAnnotations,
+        handler: async (input, registry) => lookupInstagram(input, registry)
+    }
+];
+export const MCP_TOOL_DEFINITIONS = V2_TOOL_DEFINITIONS;
+export function registerMcpTools(server, registry) {
+    for (const definition of MCP_TOOL_DEFINITIONS) {
+        server.registerTool(definition.name, {
+            title: definition.title,
+            description: definition.description,
+            inputSchema: definition.inputSchema,
+            annotations: definition.annotations
+        }, async (input) => definition.handler(input, registry));
+    }
+}
+async function requestCapability(registry, capability, input) {
+    return registry.request(capability, input);
+}
+function queryEnvelope(input, payload) {
+    return {
+        query: sanitizeQueryInput(input),
+        ...payload,
+        page: buildPage(input)
+    };
+}
+function sanitizeQueryInput(input) {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+}
+function buildPage(input) {
+    return {
+        limit: numberOrNull(input.limit),
+        offset: numberOrNull(input.offset) ?? 0
+    };
+}
+function paginate(items, input) {
+    const offset = Math.max(0, Math.trunc(numberOrNull(input.offset) ?? 0));
+    const limit = numberOrNull(input.limit);
+    return typeof limit === 'number'
+        ? items.slice(offset, offset + Math.max(0, Math.trunc(limit)))
+        : items.slice(offset);
+}
+function includesV2(input, value) {
+    return Array.isArray(input.include) && input.include.includes(value);
+}
+function includeAny(input, values) {
+    return values.some((value) => includesV2(input, value));
+}
+function buildAccountQueryItem(detail, input, exportsData) {
+    const item = {
+        account: summarizeAccount(detail.account)
+    };
+    const included = {};
+    if (includesV2(input, 'profile_snapshot')) {
+        included.profileSnapshot = detail.profileSnapshot ?? null;
+    }
+    if (includesV2(input, 'engagement_snapshot')) {
+        included.engagementSnapshot = detail.engagementSnapshot ?? null;
+    }
+    if (includesV2(input, 'audience_summary')) {
+        included.audience = buildAccountAudience(detail);
+    }
+    if (includesV2(input, 'media_summary')) {
+        included.mediaSummary = buildAccountMediaSummary(detail);
+    }
+    if (includesV2(input, 'recent_media')) {
+        included.recentMedia = paginate(buildAccountMediaViews(detail), {
+            limit: input.mediaLimit ?? input.limit,
+            offset: input.offset
+        });
+    }
+    if (exportsData !== undefined) {
+        included.exports = asArray(asObject(exportsData).exports).map(summarizeExport);
+    }
+    if (includesV2(input, 'actions')) {
+        included.actions = buildActions(asArray(detail.tasks));
+    }
+    if (Object.keys(included).length > 0) {
+        item.included = included;
+    }
+    return item;
+}
+function buildHashtagQueryItem(detail, input, exportsData) {
+    const item = {
+        hashtag: summarizeHashtag(detail.hashtag ?? { handle: input.handle })
+    };
+    const included = {};
+    if (includesV2(input, 'snapshot')) {
+        included.snapshot = detail.snapshot ?? null;
+    }
+    if (includesV2(input, 'media_summary')) {
+        included.mediaSummary = {
+            count: buildHashtagMediaViews(detail).length
+        };
+    }
+    if (includesV2(input, 'recent_media')) {
+        included.recentMedia = paginate(buildHashtagMediaViews(detail), {
+            limit: input.mediaLimit ?? input.limit,
+            offset: input.offset
+        });
+    }
+    if (includesV2(input, 'creators')) {
+        included.creators = detail.creators ?? [];
+    }
+    if (includesV2(input, 'related')) {
+        included.related = detail.relatedHashtags ?? [];
+    }
+    if (exportsData !== undefined) {
+        included.exports = asArray(asObject(exportsData).exports).map(summarizeExport);
+    }
+    if (includesV2(input, 'actions')) {
+        included.actions = buildActions(asArray(detail.tasks));
+    }
+    if (Object.keys(included).length > 0) {
+        item.included = included;
+    }
+    return item;
+}
+async function queryAudience(input, registry) {
+    const detail = await requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_GET_ACCOUNT_DETAIL, {
+        username: input.username,
+        postsLimit: 0
+    });
+    if (!detail.ok) {
+        return errorToolResponse(detail);
+    }
+    const task = findLatestTaskForAudience(asArray(asObject(detail.data).tasks), String(input.kind));
+    if (!task) {
+        return jsonToolResponse(queryEnvelope(input, {
+            results: {
+                audience: []
+            },
+            included: {
+                stats: null
+            }
+        }));
+    }
+    const response = await requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_QUERY_AUDIENCE_MEMBERS, {
+        taskId: task.id,
+        query: input.query,
+        privacy: input.privacy,
+        verification: input.verification,
+        limit: input.limit,
+        offset: input.offset
+    });
+    if (!response.ok) {
+        return errorToolResponse(response);
+    }
+    return jsonToolResponse(queryEnvelope(input, {
+        results: {
+            audience: asObject(response.data).records ?? []
+        },
+        included: {
+            stats: asObject(response.data).stats ?? null
+        }
+    }));
+}
+async function queryMedia(input, registry) {
+    const hasAccount = typeof input.account === 'string' && input.account.trim();
+    const hasHashtag = typeof input.hashtag === 'string' && input.hashtag.trim();
+    if (hasAccount && hasHashtag) {
+        return validationError('vv_media_query accepts either account or hashtag, not both.');
+    }
+    if (!hasAccount && !hasHashtag) {
+        return validationError('vv_media_query requires account or hashtag.');
+    }
+    const response = hasAccount
+        ? await requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_GET_ACCOUNT_DETAIL, {
+            username: input.account,
+            postsLimit: input.limit ?? 100
+        })
+        : await requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_GET_HASHTAG_DETAIL, {
+            handle: input.hashtag,
+            postsLimit: input.limit ?? 100
+        });
+    if (!response.ok) {
+        return errorToolResponse(response);
+    }
+    const media = hasAccount
+        ? filterMediaViews(buildAccountMediaViews(asObject(response.data)), asStringArray(input.sources))
+        : buildHashtagMediaViews(asObject(response.data));
+    const selected = findMediaView(media, input.mediaId, input.shortcode);
+    if (typeof input.mediaId === 'string' || typeof input.shortcode === 'string') {
+        return jsonToolResponse(queryEnvelope(input, { item: selected }));
+    }
+    return jsonToolResponse(queryEnvelope(input, {
+        results: {
+            media: paginate(media, input)
+        }
+    }));
+}
+async function runOperation(input, registry) {
+    const kind = String(input.kind ?? '');
+    const operationInput = asObject(input.input);
+    const normalizedInput = normalizeOperationInput(kind, operationInput);
+    if ('error' in normalizedInput) {
+        return validationError(String(normalizedInput.error));
+    }
+    const effects = describeOperationEffects(kind, normalizedInput.value);
+    if (input.dryRun === true) {
+        return jsonToolResponse({
+            dryRun: true,
+            kind,
+            normalizedInput: normalizedInput.value,
+            effects,
+            warnings: []
+        });
+    }
+    const result = await executeOperation(kind, normalizedInput.value, registry);
+    if (!result.ok) {
+        return errorToolResponse(result);
+    }
+    return jsonToolResponse({
+        dryRun: false,
+        kind,
+        normalizedInput: normalizedInput.value,
+        effects,
+        ...buildOperationRunPayload(kind, normalizedInput.value, result.data)
+    });
+}
+async function queryOperations(input, registry) {
+    const target = buildOperationQueryTarget(input);
+    const response = await requestCapability(registry, CAPABILITIES.SOCIAL_COLLECTION_LIST_TASKS, {
+        operationId: input.operationId,
+        targetHandle: target?.handle,
+        targetType: target?.type,
+        limit: input.limit
+    });
+    if (!response.ok) {
+        return errorToolResponse(response);
+    }
+    const tasks = asArray(asObject(response.data).tasks)
+        .map(asObject)
+        .filter((task) => !input.status || normalizeActionStatus(task.status) === input.status)
+        .filter((task) => !input.kind || operationKindFromCapability(String(task.capability ?? '')) === input.kind);
+    const operations = paginate(buildActions(tasks), input);
+    if (typeof input.operationId === 'string' && input.operationId.trim()) {
+        return jsonToolResponse(queryEnvelope(input, {
+            operation: operations[0] ?? null
+        }));
+    }
+    return jsonToolResponse(queryEnvelope(input, {
+        operations
+    }));
+}
+function normalizeOperationInput(kind, input) {
+    switch (kind) {
+        case 'account_track':
+            return requiredObject({
+                username: normalizeRequiredString(input.username, 'username'),
+                role: input.role
+            });
+        case 'account_update_role':
+            return requiredObject({
+                username: normalizeRequiredString(input.username, 'username'),
+                role: normalizeRequiredString(input.role, 'role')
+            });
+        case 'account_untrack':
+            return requiredObject({
+                username: normalizeRequiredString(input.username, 'username')
+            });
+        case 'account_refresh':
+            return requiredObject({
+                username: normalizeRequiredString(input.username, 'username'),
+                data: Array.isArray(input.data) && input.data.length > 0 ? input.data : ['profile', 'media'],
+                limit: input.limit,
+                mediaSources: input.mediaSources
+            });
+        case 'hashtag_track':
+        case 'hashtag_untrack':
+            return requiredObject({
+                handle: normalizeRequiredString(input.handle, 'handle')
+            });
+        case 'hashtag_refresh':
+            return requiredObject({
+                handle: normalizeRequiredString(input.handle, 'handle'),
+                limit: input.limit
+            });
+        case 'media_comments_refresh':
+            return requiredObject({
+                shortcode: normalizeRequiredString(input.shortcode, 'shortcode'),
+                commentsLimit: input.commentsLimit ?? input.limit
+            });
+        case 'media_download':
+            return requiredObject({
+                mediaItemIds: Array.isArray(input.mediaItemIds) && input.mediaItemIds.length > 0 ? input.mediaItemIds : null,
+                action: input.action ?? 'queue'
+            });
+        case 'export_create':
+            return requiredObject({
+                target: asObject(input.target),
+                username: input.username,
+                handle: input.handle,
+                dataset: input.dataset ?? input.data,
+                limit: input.limit,
+                mediaSources: input.mediaSources,
+                commentsLimit: input.commentsLimit,
+                includeComments: input.includeComments,
+                includeMediaUrls: input.includeMediaUrls
+            });
+        default:
+            return { error: `Unsupported operation kind: ${kind}` };
+    }
+}
+function requiredObject(value) {
+    const invalid = Object.entries(value).find(([, field]) => field === null);
+    if (invalid) {
+        return { error: `vv_operation_run input requires ${invalid[0]}.` };
+    }
+    return { value };
+}
+async function searchInstagram(input, registry) {
+    const targets = asStringArray(input.targets);
+    const requestedTargets = targets.length > 0 ? targets : ['accounts', 'hashtags'];
+    const libraryPromise = requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_LIST_ACCOUNTS, {});
+    const accountsPromise = requestedTargets.includes('accounts')
+        ? requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_SEARCH_ACCOUNTS, { query: input.query, limit: input.limit })
+        : null;
+    const hashtagsPromise = requestedTargets.includes('hashtags')
+        ? requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_SEARCH_HASHTAGS, { query: input.query, limit: input.limit })
+        : null;
+    const [library, accountsResult, hashtagsResult] = await Promise.all([libraryPromise, accountsPromise, hashtagsPromise]);
+    if (!library.ok) {
+        return errorToolResponse(library);
+    }
+    for (const result of [accountsResult, hashtagsResult]) {
+        if (result && !result.ok) {
+            return errorToolResponse(result);
+        }
+    }
+    const libraryData = asObject(library.data);
+    const localAccounts = new Map(asArray(libraryData.accounts).map((item) => {
+        const account = asObject(item);
+        return [normalizeUsername(account.username), account];
+    }));
+    const localHashtags = new Map(asArray(libraryData.hashtags).map((item) => {
+        const hashtag = asObject(item);
+        return [normalizeHashtag(hashtag.handle), hashtag];
+    }));
+    const accounts = accountsResult?.ok
+        ? asArray(asObject(accountsResult.data).results).map((item) => {
+            const candidate = asObject(item);
+            const local = localAccounts.get(normalizeUsername(candidate.username));
+            return { ...candidate, inLibrary: Boolean(local), isTracked: Boolean(local), targetRole: local?.targetRole ?? null };
+        })
+        : [];
+    const hashtags = hashtagsResult?.ok
+        ? asArray(asObject(hashtagsResult.data).results).map((item) => {
+            const candidate = asObject(item);
+            const local = localHashtags.get(normalizeHashtag(candidate.handle));
+            return { ...candidate, inLibrary: Boolean(local), isTracked: Boolean(local) };
+        })
+        : [];
+    return jsonToolResponse({
+        query: stringOrNull(input.query) ?? '',
+        results: { accounts, hashtags }
+    });
+}
+async function lookupInstagram(input, registry) {
+    const type = input.type;
+    const include = asStringArray(input.include);
+    if (type === 'account' && include.includes('related')) {
+        return validationError('ig_lookup account include supports only recent_media.');
+    }
+    const capability = type === 'account'
+        ? CAPABILITIES.SOCIAL_INSTAGRAM_LOOKUP_ACCOUNT
+        : CAPABILITIES.SOCIAL_INSTAGRAM_LOOKUP_HASHTAG;
+    const identifier = type === 'account'
+        ? normalizeRequiredString(input.username, 'username')
+        : normalizeRequiredString(input.hashtag, 'hashtag');
+    if (!identifier) {
+        return validationError(`ig_lookup type ${String(type)} requires ${type === 'account' ? 'username' : 'hashtag'}.`);
+    }
+    const [live, library] = await Promise.all([
+        requestCapability(registry, capability, {
+            ...(type === 'account' ? { username: identifier } : { hashtag: identifier }),
+            include,
+            mediaLimit: input.mediaLimit
+        }),
+        requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_LIST_ACCOUNTS, {})
+    ]);
+    if (!live.ok) {
+        return errorToolResponse(live);
+    }
+    if (!library.ok) {
+        return errorToolResponse(library);
+    }
+    const data = asObject(live.data);
+    const libraryData = asObject(library.data);
+    if (type === 'account') {
+        const local = asArray(libraryData.accounts).map(asObject)
+            .find((account) => normalizeUsername(account.username) === normalizeUsername(identifier));
+        return jsonToolResponse({
+            item: {
+                type: 'account',
+                profile: data.profile ?? null,
+                inLibrary: Boolean(local),
+                isTracked: Boolean(local),
+                targetRole: local?.targetRole ?? null
+            },
+            included: asObject(data.included)
+        });
+    }
+    const local = asArray(libraryData.hashtags).map(asObject)
+        .find((hashtag) => normalizeHashtag(hashtag.handle) === normalizeHashtag(identifier));
+    return jsonToolResponse({
+        item: {
+            type: 'hashtag',
+            hashtag: data.hashtag ?? `#${normalizeHashtag(identifier)}`,
+            snapshot: data.snapshot ?? null,
+            inLibrary: Boolean(local),
+            isTracked: Boolean(local)
+        },
+        included: asObject(data.included)
+    });
+}
+function normalizeUsername(value) {
+    return typeof value === 'string' ? value.trim().replace(/^@/, '').toLowerCase() : '';
+}
+function normalizeHashtag(value) {
+    return typeof value === 'string' ? value.trim().replace(/^#+/, '').toLowerCase() : '';
+}
+function normalizeRequiredString(value, name) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function describeOperationEffects(kind, input) {
+    switch (kind) {
+        case 'account_track':
+            return [`Track @${input.username} in the local Instagram library.`];
+        case 'account_update_role':
+            return [`Update local role metadata for @${input.username}.`];
+        case 'account_untrack':
+            return [`Delete @${input.username} from local tracked accounts. Instagram content is not deleted.`];
+        case 'account_refresh':
+            return asStringArray(input.data).map((dataKind) => `Queue ${dataKind} refresh for @${input.username}.`);
+        case 'hashtag_track':
+            return [`Track #${normalizeHashtagHandle(String(input.handle))} in the local Instagram library.`];
+        case 'hashtag_untrack':
+            return [`Delete #${normalizeHashtagHandle(String(input.handle))} from local tracked hashtags. Instagram content is not deleted.`];
+        case 'hashtag_refresh':
+            return [`Queue snapshot and media refresh for #${normalizeHashtagHandle(String(input.handle))}.`];
+        case 'media_comments_refresh':
+            return [`Queue comments refresh for media shortcode ${input.shortcode}.`];
+        case 'media_download':
+            return [`${String(input.action ?? 'queue')} local media downloads for ${asArray(input.mediaItemIds).length} media items.`];
+        case 'export_create':
+            return ['Create a local CSV export from saved Instagram library data.'];
+        default:
+            return [];
+    }
+}
+async function executeOperation(kind, input, registry) {
+    switch (kind) {
+        case 'account_track':
+            return requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_UPSERT_ACCOUNT_TARGET, {
+                username: input.username,
+                role: input.role
+            });
+        case 'account_update_role':
+            return requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_UPDATE_ACCOUNT_ROLE, {
+                username: input.username,
+                role: input.role
+            });
+        case 'account_untrack':
+            return requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_DELETE_ACCOUNT, {
+                username: input.username
+            });
+        case 'account_refresh': {
+            const dataKinds = asStringArray(input.data);
+            const results = [];
+            for (const dataKind of dataKinds) {
+                const response = await requestCapability(registry, CAPABILITIES.SOCIAL_COLLECTION_START, mapAccountRefreshInput(String(input.username), dataKind, input));
+                if (!response.ok) {
+                    return response;
+                }
+                results.push(response.data);
+            }
+            return {
+                ok: true,
+                requestId: 'operation-account-refresh',
+                capability: CAPABILITIES.SOCIAL_COLLECTION_START,
+                data: { results }
+            };
+        }
+        case 'hashtag_track':
+            return requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_UPSERT_HASHTAG_TARGET, {
+                handle: input.handle
+            });
+        case 'hashtag_untrack':
+            return requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_DELETE_HASHTAG, {
+                handle: input.handle
+            });
+        case 'hashtag_refresh':
+            return requestCapability(registry, CAPABILITIES.SOCIAL_COLLECTION_START, {
+                capability: 'instagram.hashtag.snapshot.collect',
+                target: {
+                    type: 'hashtag',
+                    handle: normalizeHashtagHandle(String(input.handle))
+                },
+                options: {
+                    limit: input.limit
+                }
+            });
+        case 'media_comments_refresh':
+            return requestCapability(registry, CAPABILITIES.SOCIAL_COLLECTION_START, {
+                capability: 'instagram.post.comments.collect',
+                target: {
+                    type: 'post',
+                    handle: input.shortcode
+                },
+                options: {
+                    limit: input.commentsLimit
+                }
+            });
+        case 'media_download':
+            return requestCapability(registry, CAPABILITIES.SOCIAL_MEDIA_DOWNLOAD, {
+                action: input.action ?? 'queue',
+                mediaItemIds: input.mediaItemIds
+            });
+        case 'export_create':
+            return executeExportOperation(input, registry);
+        default:
+            return {
+                ok: false,
+                requestId: null,
+                capability: null,
+                error: {
+                    code: BRIDGE_ERROR_CODES.UNSUPPORTED_CAPABILITY,
+                    message: `Unsupported operation kind: ${kind}`
+                }
+            };
+    }
+}
+async function executeExportOperation(input, registry) {
+    const target = asObject(input.target);
+    const username = stringOrNull(input.username) ?? (target.type === 'account' ? stringOrNull(target.handle) : null);
+    const handle = stringOrNull(input.handle) ?? (target.type === 'hashtag' ? stringOrNull(target.handle) : null);
+    if (username) {
+        const mapped = await mapAccountExportInput({
+            username,
+            data: input.dataset ?? 'media',
+            limit: input.limit,
+            mediaSources: input.mediaSources,
+            commentsLimit: input.commentsLimit
+        }, registry);
+        if ('error' in mapped && mapped.error) {
+            return mapped.error;
+        }
+        return requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_EXPORT_CSV, mapped.value);
+    }
+    if (handle) {
+        return requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_EXPORT_CSV, {
+            sourceType: 'hashtag_posts',
+            handle: normalizeHashtagHandle(handle),
+            limit: input.limit,
+            includeComments: input.includeComments === true,
+            includeMediaUrls: input.includeMediaUrls === true
+        });
+    }
+    return {
+        ok: false,
+        requestId: null,
+        capability: CAPABILITIES.SOCIAL_CONTEXT_EXPORT_CSV,
+        error: {
+            code: BRIDGE_ERROR_CODES.UNSUPPORTED_CAPABILITY,
+            message: 'export_create requires username, handle, or target.'
+        }
+    };
+}
+function buildOperationRunPayload(kind, input, data) {
+    if (kind === 'account_refresh') {
+        const results = asArray(asObject(data).results);
+        return {
+            operationId: stringOrNull(asObject(results[0]).operationId) ?? stringOrNull(asObject(results[0]).taskId),
+            status: 'running',
+            actions: results.map((result) => buildActionFromCollectionRun('refresh', { type: 'account', handle: String(input.username ?? '') }, result))
+        };
+    }
+    if (kind === 'hashtag_refresh' || kind === 'media_comments_refresh') {
+        const target = kind === 'hashtag_refresh'
+            ? { type: 'hashtag', handle: normalizeHashtagHandle(String(input.handle ?? '')) }
+            : { type: 'post', handle: String(input.shortcode ?? '') };
+        return {
+            operationId: stringOrNull(asObject(data).operationId) ?? stringOrNull(asObject(data).taskId),
+            status: 'running',
+            actions: [buildActionFromCollectionRun('refresh', target, data)]
+        };
+    }
+    if (kind === 'media_download') {
+        return {
+            status: 'running',
+            download: data
+        };
+    }
+    if (kind === 'export_create') {
+        return {
+            status: 'completed',
+            file: summarizeExportPayload(data)
+        };
+    }
+    return {
+        status: 'completed',
+        result: data
+    };
+}
+function buildOperationQueryTarget(input) {
+    if (typeof input.account === 'string' && input.account.trim()) {
+        return { type: 'account', handle: input.account };
+    }
+    if (typeof input.hashtag === 'string' && input.hashtag.trim()) {
+        return { type: 'hashtag', handle: normalizeHashtagHandle(input.hashtag) };
+    }
+    if (typeof input.shortcode === 'string' && input.shortcode.trim()) {
+        return { type: 'post', handle: input.shortcode };
+    }
+    return null;
+}
+function operationKindFromCapability(capability) {
+    if (capability === 'instagram.hashtag.snapshot.collect') {
+        return 'hashtag_refresh';
+    }
+    if (capability === 'instagram.post.comments.collect') {
+        return 'media_comments_refresh';
+    }
+    if (capability.includes('instagram.account') || capability.includes('instagram.audience') || capability.includes('instagram.posts')) {
+        return 'account_refresh';
+    }
+    return capability;
+}
+function validationError(message) {
+    return {
+        isError: true,
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    error: {
+                        code: BRIDGE_ERROR_CODES.VALIDATION_FAILED,
+                        message
+                    }
+                }, null, 2)
+            }]
+    };
+}
+function buildAccountProfile(detail) {
+    return {
+        account: summarizeAccount(detail.account),
+        profileSnapshot: detail.profileSnapshot ?? null,
+        engagementSnapshot: detail.engagementSnapshot ?? null
+    };
+}
+function buildAccountAudience(detail) {
+    const tasks = asArray(detail.tasks);
+    return {
+        followers: summarizeLatestAudienceTask(tasks, 'instagram.audience.followers.collect'),
+        following: summarizeLatestAudienceTask(tasks, 'instagram.audience.following.collect')
+    };
+}
+function buildAccountMediaSummary(detail) {
+    const media = buildAccountMediaViews(detail);
+    return {
+        count: media.length,
+        posts: media.filter((item) => item.source === 'post' || item.source === 'carousel').length,
+        reels: media.filter((item) => item.source === 'reel').length,
+        stories: media.filter((item) => item.source === 'story').length,
+        highlights: media.filter((item) => item.source === 'highlight').length
+    };
+}
+function summarizeLatestAudienceTask(tasks, capability) {
+    const task = tasks
+        .map(asObject)
+        .filter((item) => item.capability === capability)
+        .sort(compareUpdatedAt)[0];
+    if (!task) {
+        return null;
+    }
+    return {
+        status: normalizeActionStatus(task.status),
+        updatedAt: stringOrNull(task.updatedAt),
+        totalSaved: numberOrNull(task.totalSaved),
+        totalDiscovered: numberOrNull(task.totalDiscovered)
+    };
+}
+function buildActions(tasks) {
+    return tasks
+        .map(asObject)
+        .sort(compareUpdatedAt)
+        .map((task) => ({
+        id: stringOrNull(task.operationId) ?? String(task.id ?? ''),
+        type: inferActionTypeFromCapability(String(task.capability ?? '')),
+        status: normalizeActionStatus(task.status),
+        target: asObject(task.target),
+        capability: task.capability ?? null,
+        updatedAt: stringOrNull(task.updatedAt),
+        message: stringOrNull(task.failureReason) ?? stringOrNull(task.recommendedAction)
+    }));
+}
+function buildAccountMediaViews(detail) {
+    const mediaItems = asArray(detail.mediaItems).map((item) => fromMediaItem(asObject(item), asArray(detail.downloadTasks)));
+    const seen = new Set(mediaItems.map((item) => item.shortcode ?? item.id));
+    const legacyPosts = asArray(detail.posts)
+        .map((item) => fromPost(asObject(item), true))
+        .filter((item) => !seen.has(item.shortcode ?? item.id));
+    return [...mediaItems, ...legacyPosts].sort(compareUpdatedAtDesc);
+}
+function buildHashtagMediaViews(detail) {
+    return asArray(detail.posts).map((item) => fromPost(asObject(item), false)).sort(compareUpdatedAtDesc);
+}
+function findMediaView(media, mediaId, shortcode) {
+    const mediaIdValue = typeof mediaId === 'string' ? mediaId : null;
+    const shortcodeValue = typeof shortcode === 'string' ? shortcode : null;
+    return media.find((item) => (mediaIdValue && item.id === mediaIdValue) ||
+        (shortcodeValue && item.shortcode === shortcodeValue)) ?? null;
+}
+function filterMediaViews(media, sources) {
+    if (!sources.length) {
+        return media;
+    }
+    const normalized = new Set(sources.map((value) => normalizeMediaSourceFilter(value)));
+    return media.filter((item) => normalized.has(item.source));
+}
+function normalizeMediaSourceFilter(value) {
+    if (value === 'stories') {
+        return 'story';
+    }
+    if (value === 'highlights') {
+        return 'highlight';
+    }
+    if (value === 'reels') {
+        return 'reel';
+    }
+    return 'post';
+}
+function fromMediaItem(item, downloadTasks) {
+    const tasks = groupDownloadTasks(downloadTasks).get(String(item.id ?? '')) ?? [];
+    const assets = asArray(item.assets).map((asset) => {
+        const value = asObject(asset);
+        return {
+            type: String(value.type ?? 'image'),
+            availability: String(value.availability ?? 'unknown')
+        };
+    });
+    return {
+        id: String(item.id ?? ''),
+        source: normalizeMediaSource(String(item.sourceKind ?? 'post')),
+        shortcode: stringOrNull(item.shortcode),
+        url: stringOrNull(item.url),
+        caption: String(item.caption ?? ''),
+        authorUsername: stringOrNull(item.username),
+        metrics: {
+            likes: numberOrNull(asObject(item.metrics).likeCount),
+            comments: numberOrNull(asObject(item.metrics).commentCount),
+            views: numberOrNull(asObject(item.metrics).viewCount) ?? numberOrNull(asObject(item.metrics).playCount)
+        },
+        assets,
+        commentsAvailable: typeof item.shortcode === 'string' && item.shortcode.length > 0,
+        downloadStatus: summarizeDownloadStatus(tasks, assets.length),
+        collectedAt: String(item.collectedAt ?? ''),
+        updatedAt: String(item.updatedAt ?? '')
+    };
+}
+function fromPost(item, includeDownloadMetadata) {
+    const source = inferPostSource(item);
+    const hasAnyAsset = Boolean(item.thumbnailUrl) || Boolean(item.videoUrl);
+    return {
+        id: String(item.id ?? ''),
+        source,
+        shortcode: stringOrNull(item.shortcode),
+        url: stringOrNull(item.url),
+        caption: String(item.caption ?? ''),
+        authorUsername: stringOrNull(item.username),
+        metrics: {
+            likes: numberOrNull(item.likeCount),
+            comments: numberOrNull(item.commentCount),
+            views: numberOrNull(item.viewCount)
+        },
+        assets: [{
+                type: String(item.mediaType ?? 'image'),
+                availability: hasAnyAsset ? 'available' : 'metadata_only'
+            }],
+        commentsAvailable: typeof item.shortcode === 'string' && item.shortcode.length > 0,
+        downloadStatus: includeDownloadMetadata ? (hasAnyAsset ? 'metadata_only' : 'none') : 'metadata_only',
+        collectedAt: String(item.collectedAt ?? ''),
+        updatedAt: String(item.updatedAt ?? '')
+    };
+}
+function summarizeMediaFromPost(post) {
+    return post ? fromPost(asObject(post), false) : null;
+}
+function inferPostSource(item) {
+    const url = String(item.url ?? '');
+    if (url.includes('/reel/')) {
+        return 'reel';
+    }
+    return item.mediaType === 'carousel' ? 'carousel' : 'post';
+}
+function normalizeMediaSource(value) {
+    if (value === 'reel') {
+        return 'reel';
+    }
+    if (value === 'carousel') {
+        return 'carousel';
+    }
+    if (value === 'story') {
+        return 'story';
+    }
+    if (value === 'highlight_story') {
+        return 'highlight';
+    }
+    return 'post';
+}
+function groupDownloadTasks(tasks) {
+    const grouped = new Map();
+    for (const task of tasks.map(asObject)) {
+        const mediaItemId = String(task.mediaItemId ?? '');
+        if (!mediaItemId) {
+            continue;
+        }
+        const existing = grouped.get(mediaItemId) ?? [];
+        existing.push(task);
+        grouped.set(mediaItemId, existing);
+    }
+    return grouped;
+}
+function summarizeDownloadStatus(tasks, assetCount) {
+    if (assetCount === 0) {
+        return 'metadata_only';
+    }
+    if (tasks.length === 0) {
+        return 'none';
+    }
+    const statuses = tasks.map((task) => String(task.status ?? ''));
+    const completed = statuses.filter((status) => status === 'completed').length;
+    if (completed === assetCount && assetCount > 0) {
+        return 'completed';
+    }
+    if (statuses.some((status) => status === 'running')) {
+        return 'running';
+    }
+    if (statuses.some((status) => status === 'queued')) {
+        return 'queued';
+    }
+    if (completed > 0) {
+        return 'partial';
+    }
+    if (statuses.some((status) => status === 'failed' || status === 'cancelled' || status === 'stale_url')) {
+        return 'failed';
+    }
+    return 'none';
+}
+async function mapAccountExportInput(input, registry) {
+    const username = String(input.username ?? '');
+    const data = String(input.data ?? '');
+    if (data === 'media') {
+        return {
+            value: {
+                sourceType: 'account_media',
+                username,
+                limit: input.limit,
+                mediaSources: mapMediaSources(asStringArray(input.mediaSources))
+            }
+        };
+    }
+    if (data === 'media_comments') {
+        return {
+            value: {
+                sourceType: 'account_comments',
+                username,
+                mediaLimit: input.limit,
+                mediaSources: mapMediaSources(asStringArray(input.mediaSources)),
+                commentsLimit: input.commentsLimit
+            }
+        };
+    }
+    const detail = await requestCapability(registry, CAPABILITIES.SOCIAL_CONTEXT_GET_ACCOUNT_DETAIL, {
+        username,
+        postsLimit: 0
+    });
+    if (!detail.ok) {
+        return { error: detail };
+    }
+    const task = findLatestTaskForAudience(asArray(asObject(detail.data).tasks), data);
+    if (!task) {
+        return {
+            error: {
+                ok: false,
+                requestId: null,
+                capability: CAPABILITIES.SOCIAL_CONTEXT_EXPORT_CSV,
+                error: {
+                    code: BRIDGE_ERROR_CODES.UNSUPPORTED_CAPABILITY,
+                    message: `No saved ${data} data is available for @${username}.`
+                }
+            }
+        };
+    }
+    return {
+        value: {
+            taskId: task.id,
+            limit: input.limit
+        }
+    };
+}
+function mapMediaSources(values) {
+    const normalized = values.filter((value) => (value === 'posts' || value === 'reels' || value === 'stories' || value === 'highlights'));
+    return normalized.length > 0 ? normalized : undefined;
+}
+function mapAccountRefreshInput(username, dataKind, input) {
+    if (dataKind === 'profile') {
+        return {
+            capability: 'instagram.account.profile.snapshot',
+            target: { type: 'account', handle: username },
+            options: {
+                limit: input.limit
+            }
+        };
+    }
+    if (dataKind === 'followers') {
+        return {
+            capability: 'instagram.audience.followers.collect',
+            target: { type: 'account', handle: username },
+            options: {
+                limit: input.limit
+            }
+        };
+    }
+    if (dataKind === 'following') {
+        return {
+            capability: 'instagram.audience.following.collect',
+            target: { type: 'account', handle: username },
+            options: {
+                limit: input.limit
+            }
+        };
+    }
+    return {
+        capability: 'instagram.posts.recent.collect',
+        target: { type: 'account', handle: username },
+        options: {
+            limit: input.limit,
+            mediaSources: mapMediaSources(asStringArray(input.mediaSources))
+        }
+    };
+}
+function findLatestTaskForAudience(tasks, kind) {
+    const capability = kind === 'following'
+        ? 'instagram.audience.following.collect'
+        : 'instagram.audience.followers.collect';
+    return tasks
+        .map(asObject)
+        .filter((task) => task.capability === capability)
+        .sort(compareUpdatedAt)[0] ?? null;
+}
+function buildActionFromCollectionRun(actionType, target, data) {
+    const value = asObject(data);
+    return {
+        ...buildActionEnvelope(actionType, 'running', target),
+        actionId: stringOrNull(value.taskId),
+        result: value
+    };
+}
+function buildActionEnvelope(type, status, target) {
+    return {
+        type,
+        status,
+        target
+    };
+}
+function summarizeAccount(account) {
+    if (!account || typeof account !== 'object') {
+        return null;
+    }
+    const value = asObject(account);
+    return {
+        id: stringOrNull(value.id),
+        username: stringOrNull(value.username),
+        displayName: stringOrNull(value.displayName),
+        role: stringOrNull(value.targetRole) ?? 'uncategorized',
+        profileUrl: stringOrNull(value.profileUrl),
+        avatarUrl: stringOrNull(value.avatarUrl),
+        updatedAt: stringOrNull(value.updatedAt),
+        lastObservedAt: stringOrNull(value.lastObservedAt)
+    };
+}
+function summarizeHashtag(hashtag) {
+    if (!hashtag || typeof hashtag !== 'object') {
+        return null;
+    }
+    const value = asObject(hashtag);
+    return {
+        id: stringOrNull(value.id),
+        handle: stringOrNull(value.handle),
+        displayName: stringOrNull(value.displayName),
+        profileUrl: stringOrNull(value.profileUrl),
+        updatedAt: stringOrNull(value.updatedAt),
+        lastObservedAt: stringOrNull(value.lastObservedAt)
+    };
+}
+function summarizeExport(contextExport) {
+    const value = asObject(contextExport);
+    return {
+        id: stringOrNull(value.id),
+        filename: stringOrNull(value.filename),
+        dataType: stringOrNull(value.dataType),
+        target: value.target ?? null,
+        createdAt: stringOrNull(value.createdAt),
+        recordCount: numberOrNull(value.recordCount),
+        format: stringOrNull(value.format)
+    };
+}
+function summarizeExportPayload(data) {
+    const value = asObject(data);
+    return {
+        id: stringOrNull(value.exportId),
+        name: stringOrNull(value.filename),
+        format: stringOrNull(value.format),
+        recordCount: numberOrNull(value.recordCount),
+        content: stringOrNull(value.content),
+        csv: stringOrNull(value.csv)
+    };
+}
+function summarizeConnection(status) {
+    return {
+        connected: status.connected,
+        clientId: status.clientId,
+        extensionVersion: status.extensionVersion,
+        connectedAt: status.connectedAt,
+        lastSeenAt: status.lastSeenAt,
+        pendingRequests: status.pendingRequests
+    };
+}
+function inferActionTypeFromCapability(capability) {
+    if (capability.includes('.export') || capability.includes('comments.collect') || capability.includes('snapshot.collect')) {
+        return 'export';
+    }
+    if (capability.includes('.download')) {
+        return 'download';
+    }
+    if (capability.includes('.upsert') || capability.includes('.delete') || capability.includes('.update')) {
+        return 'manage';
+    }
+    return 'refresh';
+}
+function normalizeActionStatus(value) {
+    if (value === 'queued' || value === 'running' || value === 'completed' || value === 'failed' || value === 'cancelled') {
+        return value;
+    }
+    return 'failed';
+}
+function shouldInclude(input, value) {
+    return Array.isArray(input.include) && input.include.includes(value);
+}
+function bridgeResultToToolResponse(result) {
+    if (result.ok) {
+        return jsonToolResponse(result.data);
+    }
+    return errorToolResponse(result);
+}
+function errorToolResponse(result) {
+    if (result.ok) {
+        return jsonToolResponse(result.data);
+    }
+    return {
+        isError: true,
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    error: {
+                        ...result.error,
+                        retryAfter: extractRetryAfter(result.error.message)
+                    },
+                    requestId: result.requestId,
+                    capability: result.capability
+                }, null, 2)
+            }]
+    };
+}
+function extractRetryAfter(message) {
+    const match = /Retry after (\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z)/.exec(message);
+    return match?.[1];
+}
+function jsonToolResponse(value) {
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(value, null, 2)
+            }]
+    };
+}
+function asObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asStringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string')
+        : [];
+}
+function stringOrNull(value) {
+    return typeof value === 'string' && value.trim() ? value : null;
+}
+function numberOrNull(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function matchesSearch(value, query) {
+    const object = asObject(value);
+    return [
+        object.username,
+        object.displayName,
+        object.handle
+    ].some((field) => typeof field === 'string' && field.toLowerCase().includes(query));
+}
+function compareUpdatedAt(left, right) {
+    return String(right.updatedAt ?? '').localeCompare(String(left.updatedAt ?? ''));
+}
+function compareUpdatedAtDesc(left, right) {
+    return String(right.updatedAt || right.collectedAt).localeCompare(String(left.updatedAt || left.collectedAt));
+}
+function normalizeHashtagHandle(value) {
+    return value.trim().replace(/^#+/, '').trim().toLowerCase();
+}