@withpica/mcp-server 1.3.0

package/dist/tools/discovery.js

@@ -0,0 +1,851 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { getToolMetadata } from "./metadata.js";
+import { RECOVERY_HINTS } from "./recovery-hints.js";
+const SCHEMA_VERSION = "2026.1";
+/**
+ * Hand-maintained category taxonomy for the catalog server.
+ * Grouped by natural entity/capability prefix.
+ * Cross-server depends_on declarations use "<server-slug>:<category>" format.
+ *
+ * Exported so `scripts/lint-mcp-tools.ts` can enforce taxonomy completeness
+ * (every registered tool ∈ taxonomy ∪ archetype-allowlist) at
+ * prepublishOnly time. Sealed after the bug class bit four times — silently
+ * for `pica_upload` + `pica_download` since ADR-152, for `pica_submit_feedback`
+ * since ADR-184, and again for `pica_report_issue` + `pica_my_reported_issues`
+ * (ADR-196 Phase 3) which were the exact failure mode they were designed to
+ * catch and so couldn't catch themselves. ~95 further pre-existing violators
+ * are grandfathered in `scripts/mcp-tool-lint-baseline.json` for retrofit.
+ */
+export const CATEGORIES = {
+    works: {
+        description: "manage your musical works",
+        tools: [
+            "pica_works_query",
+            "pica_works_inspect",
+            "pica_works_create",
+            "pica_works_update",
+            "pica_works_delete",
+            "pica_works_bulk_delete",
+            "pica_works_bulk_update",
+            "pica_works_verify",
+        ],
+        depends_on: [],
+    },
+    people: {
+        description: "manage people in your catalog",
+        tools: [
+            "pica_people_query",
+            "pica_people_inspect",
+            "pica_people_create",
+            "pica_people_update",
+            "pica_people_delete",
+            "pica_people_bulk_update_roles",
+            "pica_group_add_member",
+            "pica_group_remove_member",
+            "pica_group_list_members",
+            "pica_person_list_groups",
+        ],
+        depends_on: [],
+    },
+    groups: {
+        description: "manage group → member relationships on people (ADR-223)",
+        tools: [
+            "pica_group_add_member",
+            "pica_group_remove_member",
+            "pica_group_list_members",
+            "pica_person_list_groups",
+        ],
+        depends_on: [],
+    },
+    recordings: {
+        description: "manage recordings linked to works",
+        tools: [
+            "pica_recordings_query",
+            "pica_recordings_inspect",
+            "pica_recordings_create",
+            "pica_recordings_update",
+            "pica_recordings_delete",
+        ],
+        depends_on: [],
+    },
+    credits: {
+        description: "manage work credits, contributors, and first-party recording-side production credits",
+        tools: [
+            "pica_credits_list",
+            "pica_credits_update",
+            "pica_recording_credits_update",
+        ],
+        depends_on: [],
+    },
+    multimedia: {
+        description: "manage photos, videos, and media linked to works",
+        tools: [
+            "pica_multimedia_search",
+            "pica_multimedia_create",
+            "pica_multimedia_import_url",
+            "pica_multimedia_link_youtube",
+            "pica_multimedia_link_work",
+        ],
+        depends_on: [],
+    },
+    audio: {
+        description: "manage and analyze audio files",
+        tools: [
+            "pica_audio_query",
+            "pica_audio_inspect",
+            "pica_audio_presigned_upload",
+            "pica_audio_complete_upload",
+            "pica_audio_analyze",
+            "pica_audio_identify",
+        ],
+        depends_on: [],
+    },
+    projects: {
+        description: "manage albums, EPs, and work groupings",
+        tools: [
+            "pica_projects_list",
+            "pica_projects_get",
+            "pica_projects_create",
+            "pica_projects_update",
+            "pica_projects_delete",
+            "pica_projects_attach_works",
+        ],
+        depends_on: [],
+    },
+    releases: {
+        description: "manage releases with dates, labels, and UPCs",
+        tools: [
+            "pica_releases_list",
+            "pica_releases_get",
+            "pica_releases_create",
+            "pica_releases_update",
+            // ADR-175 workflow tools
+            "pica_releases_bulk_attach_tracks",
+            "pica_releases_move_track",
+            "pica_releases_attach_track_by_identifier",
+            "pica_releases_create_with_tracks",
+            "pica_releases_completeness_check",
+            // Track attach/detach + ordering
+            "pica_releases_attach_track",
+            "pica_releases_attach_recording_with_work",
+            "pica_releases_detach_track",
+            "pica_releases_list_tracks",
+            "pica_releases_reorder_tracks",
+            // ADR-208 Phase 3 Primitive D — rich render
+            "pica_release_show",
+        ],
+        depends_on: [],
+    },
+    sessions: {
+        description: "track work sessions and studio time",
+        tools: [
+            "pica_sessions_list",
+            "pica_sessions_get",
+            "pica_sessions_create",
+            "pica_sessions_types",
+        ],
+        depends_on: [],
+    },
+    notes: {
+        description: "create and manage catalog notes",
+        tools: [
+            "pica_notes_list",
+            "pica_notes_get",
+            "pica_notes_create",
+            "pica_notes_delete",
+        ],
+        depends_on: [],
+    },
+    duplicates: {
+        description: "detect and merge duplicate records",
+        tools: ["pica_find_duplicates", "pica_merge_duplicates"],
+        depends_on: [],
+    },
+    import: {
+        description: "import catalog data from files and streaming services",
+        tools: [
+            "pica_import_fields",
+            "pica_import_template",
+            "pica_import_analyze",
+            "pica_import_validate",
+            "pica_import_execute",
+            "pica_import_streaming_link",
+            "pica_import_from_spotify",
+            "pica_import_documents_query",
+            "pica_import_documents_inspect",
+            "pica_import_youtube_link",
+            "pica_ingest_statement",
+        ],
+        depends_on: [],
+    },
+    export: {
+        description: "export catalog data in various formats",
+        tools: [
+            "pica_export_catalog_csv",
+            "pica_export_song_registration",
+            "pica_export_industry_ready",
+            "pica_export_catalog_asset_report",
+            "pica_export_ai_consent",
+            // Interactive download card (ADR-152) — pair with any export tool to
+            // deliver the file directly. Lives here rather than in `uploads`
+            // because it's the delivery side of the export flow.
+            "pica_download",
+        ],
+        depends_on: [
+            "mcp-server-business:agreements",
+            "mcp-server-business:splits",
+        ],
+    },
+    search: {
+        description: "search across the catalog and discover content",
+        tools: [
+            "pica_search_all",
+            "pica_catalog_stats",
+            "pica_graph_traverse",
+            "pica_discoveries_query",
+            "pica_discoveries_review",
+            "pica_claim_credit",
+            "pica_claim_custody",
+            "pica_claim_artist",
+        ],
+        depends_on: [],
+    },
+    analytics: {
+        description: "provenance, carbon, and catalog analytics",
+        tools: [
+            "pica_provenance_stats",
+            "pica_provenance_work",
+            "pica_provenance_certificate",
+            "pica_carbon_footprint",
+            "pica_carbon_live",
+            "pica_catalog_diligence",
+            // Reconciliation cascades + audit log + CAR preview
+            "pica_run_person_cascade",
+            "pica_run_work_cascade",
+            "pica_cascade_health",
+            "pica_car_preview",
+            "pica_audit_list",
+        ],
+        depends_on: ["mcp-server-business:agreements"],
+    },
+    documents: {
+        description: "analyse documents with ai",
+        tools: ["pica_documents_analyse"],
+        depends_on: [],
+    },
+    calendar: {
+        description: "view catalog calendar events",
+        tools: ["pica_calendar_events"],
+        depends_on: [],
+    },
+    publishers: {
+        description: "look up and create publishers",
+        tools: ["pica_publishers_query", "pica_publishers_create"],
+        depends_on: [],
+    },
+    briefing: {
+        description: "get your daily catalog briefing and dashboard",
+        tools: [
+            "pica_dashboard_attention",
+            "pica_dashboard_briefing",
+            "pica_dashboard_pulse",
+        ],
+        depends_on: [],
+    },
+    enrichment: {
+        description: "enrich your catalog metadata from external sources",
+        tools: [
+            // ADR-179 outcome-shaped resolvers own the enrichment surface;
+            // the seven per-source tombstones were removed in ADR-154 F13.
+            "pica_resolve_work",
+            "pica_resolve_person",
+            "pica_resolve_recording",
+            "pica_enrichment_candidates",
+            "pica_enrichment_compare",
+            "pica_registrations_compare",
+            // Agent-proposed enrichment (ADR-178) routes through review gates
+            "pica_enrichment_propose",
+            "pica_enrichment_proposal_apply",
+            "pica_enrichment_proposal_reject",
+            "pica_enrichment_proposals_list",
+        ],
+        depends_on: [],
+    },
+    team: {
+        description: "manage your team members and roles",
+        tools: [
+            "pica_team_list",
+            "pica_team_get",
+            "pica_team_invite",
+            "pica_team_update_role",
+            "pica_team_remove",
+        ],
+        depends_on: [],
+    },
+    feedback: {
+        description: "report problems and submit feedback to the PICA team — call proactively when you hit a workflow gap or the user says 'this is broken'",
+        tools: [
+            // Customer-facing issue + feedback surface (ADR-184 + ADR-196).
+            // Listed here so the layered-discovery flow exposes them — without
+            // this entry, agents using pica_discover cannot reach the tools and
+            // resort to pica_notes_create as the closest match (a real
+            // production failure caught 2026-04-25).
+            "pica_report_issue",
+            "pica_my_reported_issues",
+            "pica_submit_feedback",
+        ],
+        depends_on: [],
+    },
+    onboarding: {
+        description: "acknowledge MCP onboarding for OAuth-arrived users — call after walking the user through identity, security, and intent",
+        tools: [
+            // Listed so layered-discovery flows expose it; the auth-boundary
+            // gate in /api/mcp also unconditionally allows this tool through
+            // even when a customer key's scopes wouldn't ordinarily.
+            "pica_acknowledge_onboarding",
+        ],
+        depends_on: [],
+    },
+    signup: {
+        // ADR-211 Phase 1 — agent-discoverable signup verb. Listed so the
+        // layered-discovery flow surfaces the unauthenticated entry point;
+        // the public mint endpoint at /api/public/onboarding/signup-start
+        // enforces rate limits + claim shape, and the lobby tool-registry
+        // filter exposes only this tool (alongside pica_sign_in / pica_sign_out
+        // per the 2026-04-30 amendment) until the user authenticates.
+        description: "create a new withPICA account from inside the agent — for users without a connection key. existing users use pica_sign_in instead.",
+        tools: ["pica_signup_start"],
+        depends_on: [],
+    },
+    memory: {
+        description: "save and recall workspace memories across sessions",
+        tools: [
+            "pica_memory_list",
+            "pica_memory_search",
+            "pica_memory_save",
+            "pica_memory_delete",
+        ],
+        depends_on: [],
+    },
+    account: {
+        // ADR-217 — added pica_storage_configure_start + pica_storage_disconnect
+        // alongside the existing read tool so layered-discovery flows surface
+        // the full BYOC storage trio in one bucket.
+        description: "check storage and integrations; connect your own cloud storage (BYOC) or revert to PICA-managed",
+        tools: [
+            "pica_storage_status",
+            "pica_storage_configure_start",
+            "pica_storage_disconnect",
+            "pica_integrations_status",
+        ],
+        depends_on: [],
+    },
+    subscription: {
+        description: "view your billing state, manage your subscription, and pick a tier",
+        tools: ["pica_subscription_status", "pica_subscription_manage"],
+        depends_on: [],
+    },
+    profile: {
+        description: "manage your user, organisation, and directory profile",
+        tools: [
+            "pica_user_profile",
+            "pica_organisation_profile",
+            "pica_directory_settings",
+            "pica_update_my_identity",
+            "pica_update_organisation_profile",
+        ],
+        depends_on: [],
+    },
+    privacy: {
+        description: "self-service privacy & account controls — read/update marketing " +
+            "opt-ins, request GDPR data export, delete your account",
+        tools: [
+            "pica_get_privacy_settings",
+            "pica_update_privacy_settings",
+            "pica_export_my_data",
+            "pica_delete_my_account",
+        ],
+        depends_on: [],
+    },
+    uploads: {
+        description: "upload files to the platform",
+        tools: [
+            // Interactive iframe card (ADR-152) — for harness clients that can
+            // render UI. External clients (ChatGPT, Gemini) get told to upload
+            // at withpica.com/workspace via the tool's description.
+            "pica_upload",
+            // Programmatic two-step upload — for when file details are known.
+            "pica_upload_file",
+            "pica_upload_complete",
+        ],
+        depends_on: [],
+    },
+    agreements: {
+        description: "manage agreements, agreement templates, and agreement types",
+        tools: [
+            "pica_agreements_query",
+            "pica_agreements_inspect",
+            "pica_agreements_create",
+            "pica_agreements_update",
+            "pica_agreements_delete",
+            "pica_agreements_link_work",
+            "pica_agreement_templates_duplicate",
+            "pica_agreement_templates_render",
+            "pica_agreement_templates_set_default",
+            "pica_agreement_types_query",
+            "pica_agreement_types_inspect",
+            "pica_agreement_types_create",
+            "pica_agreement_types_update",
+            "pica_agreement_types_delete",
+        ],
+        depends_on: [],
+    },
+    collaborators: {
+        description: "invite, accept, and dispute catalog collaborators",
+        tools: [
+            "pica_collaborators_invite",
+            "pica_collaborators_invite_bulk",
+            "pica_collaborators_invite_resend",
+            "pica_collaborators_invites_list",
+            "pica_collaborators_incoming_list",
+            "pica_collaborators_accept",
+            "pica_collaborators_dispute",
+            "pica_disputes_list",
+        ],
+        depends_on: [],
+    },
+    custody: {
+        description: "manage catalog custody claims and reconciliation",
+        tools: [
+            "pica_custody_list",
+            "pica_custody_history",
+            "pica_custody_claim",
+            "pica_custody_respond",
+            "pica_custody_reconcile",
+            "pica_custody_resolve_pending",
+        ],
+        depends_on: [],
+    },
+    physical_assets: {
+        description: "manage physical assets (master tapes, hardware, artefacts)",
+        tools: [
+            "pica_physical_assets_query",
+            "pica_physical_assets_inspect",
+            "pica_physical_assets_create",
+            "pica_physical_assets_update",
+            "pica_physical_assets_delete",
+            "pica_physical_assets_export",
+            "pica_physical_assets_stats",
+            "pica_physical_assets_link_work",
+            "pica_physical_assets_link_recording",
+            "pica_physical_assets_unlink_work",
+            "pica_physical_assets_unlink_recording",
+        ],
+        depends_on: [],
+    },
+    recording_splits: {
+        description: "manage recording (master) splits between contributors",
+        tools: [
+            "pica_recording_splits_list",
+            "pica_recording_splits_create",
+            "pica_recording_splits_verify",
+        ],
+        depends_on: [],
+    },
+    royalties_statements: {
+        description: "view royalties and ingested statements",
+        tools: [
+            "pica_royalties_summary",
+            "pica_royalties_list",
+            "pica_royalties_get",
+            "pica_statements_list",
+            "pica_statements_get",
+        ],
+        depends_on: [],
+    },
+    share_links: {
+        description: "create, inspect, update, and delete share links for catalog content",
+        tools: [
+            "pica_share_links_create",
+            "pica_share_links_list",
+            "pica_share_links_inspect",
+            "pica_share_links_update",
+            "pica_share_links_delete",
+        ],
+        depends_on: [],
+    },
+    split_sheets: {
+        description: "generate, send, and look up split sheets",
+        tools: [
+            "pica_split_sheet_generate",
+            "pica_split_sheet_send",
+            "pica_split_sheet_get",
+            "pica_split_sheet_list",
+        ],
+        depends_on: [],
+    },
+    licensing: {
+        description: "submit, list, and respond to license enquiries; search for sync",
+        tools: [
+            "pica_submit_license_enquiry",
+            "pica_get_license_enquiry",
+            "pica_list_license_enquiries",
+            "pica_update_license_enquiry_status",
+            "pica_search_for_sync",
+        ],
+        depends_on: [],
+    },
+    sync_placements: {
+        description: "manage sync placements (films/TV/ads/games licensing your works) — placement records, evidence, verification state",
+        tools: [
+            "pica_sync_placements_query",
+            "pica_sync_placements_inspect",
+            "pica_sync_placements_create",
+            "pica_sync_placements_update",
+            "pica_sync_placements_delete",
+            "pica_sync_placements_cite",
+        ],
+        depends_on: [],
+    },
+    notifications: {
+        description: "list and schedule notifications to users and people",
+        tools: [
+            "pica_notifications_list",
+            "pica_notifications_mark_read",
+            "pica_notify_user",
+            "pica_notify_user_at",
+            "pica_notify_user_cancel",
+            "pica_notify_user_list_pending",
+            "pica_notify_person",
+            // ADR-218 — cross-transport awareness via discovery_events ledger
+            "pica_notifications_recent",
+            "pica_notification_acknowledge",
+        ],
+        depends_on: [],
+    },
+    messaging: {
+        description: "send and resend messages to collaborators and contacts",
+        tools: ["pica_send_message", "pica_send_resend", "pica_send_query"],
+        depends_on: [],
+    },
+    agent_identity: {
+        description: "manage AI agent identities, grants, and activity",
+        tools: [
+            "pica_create_agent_identity",
+            "pica_issue_agent_grant",
+            "pica_revoke_agent_grant",
+            "pica_list_my_agent_grants",
+            "pica_get_agent_activity",
+        ],
+        depends_on: [],
+    },
+    telegram: {
+        description: "connect and inspect Telegram channel for the workspace",
+        tools: ["pica_telegram_connect", "pica_telegram_status"],
+        depends_on: [],
+    },
+    labels: {
+        description: "look up record labels",
+        tools: ["pica_labels_query"],
+        depends_on: [],
+    },
+};
+/**
+ * Operational metadata defaults for pica_tool_details responses.
+ * These are reasonable defaults — _query tools return pages, _inspect/_get return one.
+ */
+function getOperationalMeta(toolName) {
+    if (toolName.endsWith("_query") || toolName.endsWith("_list")) {
+        return { max_results_per_page: 100, paginated: true };
+    }
+    if (toolName.endsWith("_inspect") ||
+        toolName.endsWith("_get") ||
+        toolName.endsWith("_get_full")) {
+        return { max_results_per_page: 1, paginated: false };
+    }
+    return {};
+}
+export class DiscoveryTools {
+    executeToolFn;
+    getToolDef;
+    constructor(executeToolFn, getToolDef) {
+        this.executeToolFn = executeToolFn;
+        this.getToolDef = getToolDef;
+    }
+    getTools() {
+        return [
+            this.buildDiscoverTool(),
+            this.buildToolDetailsTool(),
+            this.buildExecuteTool(),
+        ];
+    }
+    buildDiscoverTool() {
+        return {
+            definition: {
+                name: "pica_discover",
+                description: "Discover available tool categories. Returns a versioned summary of categories with tool counts and names. " +
+                    "Use pica_tool_details to drill into a category and get full schemas before calling tools.",
+                workflows: "infrastructure",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+                annotations: {
+                    title: "discover tool categories",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
+            },
+            executor: async () => {
+                const categories = {};
+                for (const [key, cat] of Object.entries(CATEGORIES)) {
+                    categories[key] = {
+                        description: cat.description,
+                        tool_count: cat.tools.length,
+                        tools: cat.tools,
+                        depends_on: cat.depends_on,
+                    };
+                }
+                const cacheUntil = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();
+                const payload = {
+                    schema_version: SCHEMA_VERSION,
+                    cache_until: cacheUntil,
+                    categories,
+                };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(payload, null, 2),
+                        },
+                    ],
+                    structuredContent: payload,
+                };
+            },
+        };
+    }
+    buildToolDetailsTool() {
+        return {
+            definition: {
+                name: "pica_tool_details",
+                description: "Get full schema and metadata for one tool or all tools in a category. " +
+                    "Pass either { tool: 'name' } or { category: 'name' } (from pica_discover). " +
+                    "Returns schema, annotations, recovery hints, and operational metadata.",
+                workflows: "infrastructure",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        tool: {
+                            type: "string",
+                            description: "Specific tool name (e.g. pica_works_inspect)",
+                        },
+                        category: {
+                            type: "string",
+                            description: "Category name from pica_discover (e.g. works)",
+                        },
+                    },
+                },
+                annotations: {
+                    title: "get tool details",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
+            },
+            executor: async (args) => {
+                if (args.tool) {
+                    const detail = this.buildToolDetail(args.tool);
+                    if (!detail) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        error_code: "TOOL_NOT_FOUND",
+                                        tool: args.tool,
+                                        message: `no tool named '${args.tool}' — use pica_discover to see available categories`,
+                                        retry_eligible: false,
+                                    }, null, 2),
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(detail, null, 2) }],
+                        structuredContent: detail,
+                    };
+                }
+                if (args.category) {
+                    const cat = CATEGORIES[args.category];
+                    if (!cat) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        error_code: "CATEGORY_NOT_FOUND",
+                                        category: args.category,
+                                        message: `no category '${args.category}' — use pica_discover to see available categories`,
+                                        retry_eligible: false,
+                                    }, null, 2),
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    const details = cat.tools
+                        .map((name) => this.buildToolDetail(name))
+                        .filter((d) => d !== null);
+                    const payload = {
+                        category: args.category,
+                        tool_count: details.length,
+                        tools: details,
+                    };
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+                        structuredContent: payload,
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error_code: "VALIDATION_ERROR",
+                                message: "provide either { tool: 'name' } or { category: 'name' }",
+                                retry_eligible: false,
+                            }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+            },
+        };
+    }
+    buildToolDetail(toolName) {
+        const registered = this.getToolDef(toolName);
+        const metadata = getToolMetadata(toolName);
+        // Return null when the tool is completely unknown (not registered and not in metadata)
+        if (!registered && !metadata) {
+            return null;
+        }
+        // Collect all recovery hints for this tool (all error codes)
+        const hints = RECOVERY_HINTS[toolName] ?? [];
+        const definition = registered?.definition ?? null;
+        return {
+            tool: toolName,
+            description: definition?.description ?? metadata?.display_name ?? toolName,
+            schema: definition?.inputSchema ?? null,
+            annotations: definition?.annotations ?? null,
+            metadata: metadata
+                ? {
+                    category: metadata.category,
+                    risk: metadata.risk,
+                    retry_safe: metadata.retry_safe,
+                    display_name: metadata.display_name,
+                }
+                : null,
+            recovery_hints: hints,
+            operational: getOperationalMeta(toolName),
+        };
+    }
+    buildExecuteTool() {
+        return {
+            definition: {
+                name: "pica_execute",
+                description: "Execute any catalog tool by name. " +
+                    "Use pica_discover to find categories, pica_tool_details to get the schema, then call here with { tool, args }.",
+                workflows: "infrastructure",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        tool: {
+                            type: "string",
+                            description: "Tool name to execute (e.g. pica_works_inspect). Use pica_discover + pica_tool_details to find available tools.",
+                        },
+                        args: {
+                            type: "object",
+                            additionalProperties: true,
+                            description: "Arguments to pass to the tool",
+                        },
+                    },
+                    required: ["tool"],
+                },
+                annotations: {
+                    title: "execute a catalog tool",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
+            },
+            executor: async (args, ctx) => {
+                const toolName = args.tool;
+                const toolArgs = args.args ?? {};
+                if (!toolName || typeof toolName !== "string" || !toolName.trim()) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    error_code: "VALIDATION_ERROR",
+                                    tool: null,
+                                    message: "missing required field: tool",
+                                    retry_eligible: false,
+                                }, null, 2),
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Block meta-tool self-invocation to prevent infinite loops
+                const META_TOOLS = new Set([
+                    "pica_discover",
+                    "pica_tool_details",
+                    "pica_execute",
+                ]);
+                if (META_TOOLS.has(toolName)) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    error_code: "INVALID_TOOL",
+                                    tool: toolName,
+                                    message: "meta-tools (pica_discover, pica_tool_details, pica_execute) cannot be invoked via pica_execute",
+                                    retry_eligible: false,
+                                }, null, 2),
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                try {
+                    return await this.executeToolFn(toolName, toolArgs, ctx);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    error_code: "EXECUTION_ERROR",
+                                    tool: toolName,
+                                    message,
+                                    retry_eligible: false,
+                                }, null, 2),
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        };
+    }
+}
+//# sourceMappingURL=discovery.js.map