@withpica/mcp-server 1.3.0

package/dist/tools/recovery-hints.js

@@ -0,0 +1,827 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+export const RECOVERY_HINTS = {
+    // ── destructive tools ──
+    pica_works_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "search for the work by title",
+            next_tool: "pica_works_query",
+        },
+        {
+            error_code: "HAS_DEPENDENCIES",
+            suggestion: "check what's linked to this work first",
+            next_tool: "pica_works_inspect",
+        },
+    ],
+    pica_works_bulk_delete: [
+        {
+            error_code: "PARTIAL_NOT_FOUND",
+            suggestion: "some IDs not found — list your works to verify",
+            next_tool: "pica_works_query",
+        },
+    ],
+    pica_people_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "search for the person by name",
+            next_tool: "pica_people_query",
+        },
+        {
+            error_code: "PERSON_HAS_CREDITS",
+            suggestion: "check their credits before removing",
+            next_tool: "pica_people_inspect",
+        },
+    ],
+    pica_recordings_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list recordings for this work",
+            next_tool: "pica_recordings_query",
+        },
+    ],
+    pica_agreements_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your agreements to find the right one",
+            next_tool: "pica_agreements_query",
+        },
+        {
+            error_code: "HAS_LINKED_WORKS",
+            suggestion: "check what works are linked",
+            next_tool: "pica_agreements_inspect",
+        },
+    ],
+    pica_projects_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your projects",
+            next_tool: "pica_projects_list",
+        },
+    ],
+    pica_merge_duplicates: [
+        {
+            error_code: "ENTITY_NOT_FOUND",
+            suggestion: "check both entities exist",
+            next_tool: "pica_find_duplicates",
+        },
+        {
+            error_code: "MERGE_CONFLICT",
+            suggestion: "compare the entities first",
+            next_tool: "pica_enrichment_compare",
+        },
+    ],
+    pica_team_remove: [
+        {
+            error_code: "CANNOT_REMOVE_OWNER",
+            suggestion: "check team roles",
+            next_tool: "pica_team_list",
+        },
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list team members",
+            next_tool: "pica_team_list",
+        },
+    ],
+    pica_notes_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your notes",
+            next_tool: "pica_notes_list",
+        },
+    ],
+    pica_memory_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your memories",
+            next_tool: "pica_memory_list",
+        },
+    ],
+    pica_physical_assets_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your assets",
+            next_tool: "pica_physical_assets_query",
+        },
+    ],
+    pica_agreement_templates_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your agreement templates",
+            next_tool: "pica_agreement_templates_list",
+        },
+    ],
+    pica_producer_agreements_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your producer agreements",
+            next_tool: "pica_producer_agreements_list",
+        },
+    ],
+    pica_work_for_hire_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your work-for-hire agreements",
+            next_tool: "pica_work_for_hire_list",
+        },
+    ],
+    // ── enrichment tools ──
+    //
+    // ADR-154 F13 (2026-04-21): the seven per-source `pica_enrich_work_*`
+    // and `pica_people_enrich_*` tools have been removed — their
+    // per-error hints lived here and were removed with them. The
+    // outcome-shaped resolvers `pica_resolve_work` / `pica_resolve_person`
+    // own the recovery surface now; NO_MATCH per source is returned in
+    // the structured `errors[]` receipt instead of via a tool-scoped hint.
+    // pica_resolve_work CREDIT_INSUFFICIENT hint dropped 2026-04-22 — the only
+    // hint it carried pointed at pica_credits_balance, which no longer exists
+    // (billing model is subscription). The resolver's own error receipt is
+    // authoritative. See docs/MCP_REFINEMENT_LOG.md entry B-001.
+    // ── mutating tools ──
+    pica_works_create: [
+        {
+            error_code: "DUPLICATE_WORK",
+            suggestion: "a similar work already exists — search first",
+            next_tool: "pica_works_query",
+        },
+    ],
+    pica_works_update: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "search for the work by title first",
+            next_tool: "pica_works_query",
+        },
+        {
+            error_code: "VALIDATION_ERROR",
+            suggestion: "inspect the work to see the current shape",
+            next_tool: "pica_works_inspect",
+        },
+    ],
+    pica_works_bulk_update: [
+        {
+            error_code: "PARTIAL_NOT_FOUND",
+            suggestion: "some work IDs not found — list works to verify",
+            next_tool: "pica_works_query",
+        },
+        {
+            error_code: "VALIDATION_ERROR",
+            suggestion: "inspect a sample work to see which fields are accepted",
+            next_tool: "pica_works_inspect",
+        },
+    ],
+    pica_people_create: [
+        {
+            error_code: "DUPLICATE_PERSON",
+            suggestion: "a similar person already exists — search first",
+            next_tool: "pica_people_query",
+        },
+    ],
+    pica_people_update: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "search for the person by name first",
+            next_tool: "pica_people_query",
+        },
+    ],
+    pica_people_bulk_update_roles: [
+        {
+            error_code: "PARTIAL_NOT_FOUND",
+            suggestion: "some person IDs not found — list people to verify",
+            next_tool: "pica_people_query",
+        },
+    ],
+    pica_recordings_update: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list recordings to find the right id",
+            next_tool: "pica_recordings_query",
+        },
+    ],
+    pica_credits_update: [
+        {
+            error_code: "SPLITS_NOT_100",
+            suggestion: "credit splits must total 100% — check current splits",
+            next_tool: "pica_credits_list",
+        },
+        {
+            error_code: "PERSON_NOT_FOUND",
+            suggestion: "person not in catalog — create them first",
+            next_tool: "pica_people_create",
+        },
+    ],
+    pica_recording_credits_update: [
+        {
+            error_code: "RECORDING_NOT_FOUND",
+            suggestion: "list recordings to find the right id",
+            next_tool: "pica_recordings_query",
+        },
+        {
+            error_code: "PERSON_NOT_FOUND",
+            suggestion: "person not in catalog — create them first",
+            next_tool: "pica_people_create",
+        },
+    ],
+    pica_recording_splits_create: [
+        {
+            error_code: "RECORDING_NOT_FOUND",
+            suggestion: "list recordings to find the right id",
+            next_tool: "pica_recordings_query",
+        },
+        {
+            error_code: "SPLITS_NOT_100",
+            suggestion: "splits must total 100% — inspect existing splits first",
+            next_tool: "pica_recordings_inspect",
+        },
+    ],
+    pica_split_sheet_generate: [
+        {
+            error_code: "SPLITS_NOT_100",
+            suggestion: "fix credits before generating split sheet",
+            next_tool: "pica_credits_update",
+        },
+    ],
+    pica_import_execute: [
+        {
+            error_code: "VALIDATION_ERROR",
+            suggestion: "validate the import first to see row-level issues",
+            next_tool: "pica_import_validate",
+        },
+    ],
+    pica_import_from_spotify: [
+        {
+            error_code: "INVALID_URI",
+            suggestion: "search for the artist or track first to find a valid Spotify URI",
+            next_tool: "pica_search_all",
+        },
+    ],
+    pica_import_streaming_link: [
+        {
+            error_code: "INVALID_URI",
+            suggestion: "search for the artist or track first to find a valid streaming URI",
+            next_tool: "pica_search_all",
+        },
+    ],
+    pica_import_youtube_link: [
+        {
+            error_code: "INVALID_URI",
+            suggestion: "search for the artist or track first to find a valid YouTube link",
+            next_tool: "pica_search_all",
+        },
+    ],
+    // CREDIT_INSUFFICIENT hints for pica_export_song_registration /
+    // pica_export_catalog_asset_report / pica_audio_analyze dropped 2026-04-22 —
+    // all pointed at pica_credits_balance, which no longer exists.
+    // See docs/MCP_REFINEMENT_LOG.md entry B-001.
+    pica_audio_identify: [
+        {
+            error_code: "NO_MATCH",
+            suggestion: "no fingerprint match — enter metadata manually",
+            next_tool: "pica_works_update",
+        },
+    ],
+    pica_notify_person: [
+        {
+            error_code: "NOT_PICA_USER",
+            suggestion: "person isn't on PICA — invite them first",
+            next_tool: "pica_collaborators_invite",
+        },
+    ],
+    pica_recordings_create: [
+        {
+            error_code: "DUPLICATE_ISRC",
+            suggestion: "recording with this ISRC already exists",
+            next_tool: "pica_recordings_query",
+        },
+    ],
+    // ── agreements stack ──
+    pica_agreements_create: [
+        {
+            error_code: "MISSING_COUNTERPARTY",
+            suggestion: "look up the counterparty org by name to get its UUID",
+            next_tool: "pica_search_all",
+        },
+    ],
+    pica_agreements_update: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your agreements to find the right id",
+            next_tool: "pica_agreements_query",
+        },
+    ],
+    pica_agreements_link_work: [
+        {
+            error_code: "AGREEMENT_NOT_FOUND",
+            suggestion: "list your agreements first",
+            next_tool: "pica_agreements_query",
+        },
+        {
+            error_code: "WORK_NOT_FOUND",
+            suggestion: "search for the work by title",
+            next_tool: "pica_works_query",
+        },
+    ],
+    pica_agreement_templates_duplicate: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your agreement templates to find the right id",
+            next_tool: "pica_agreement_templates_list",
+        },
+    ],
+    pica_agreement_templates_set_default: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your agreement templates to find the right id",
+            next_tool: "pica_agreement_templates_list",
+        },
+    ],
+    // ── releases ──
+    pica_releases_create: [
+        {
+            error_code: "DUPLICATE_RELEASE",
+            suggestion: "a release with this title or UPC already exists",
+            next_tool: "pica_releases_list",
+        },
+    ],
+    pica_releases_create_with_tracks: [
+        {
+            error_code: "DUPLICATE_RELEASE",
+            suggestion: "a release with this title or UPC already exists",
+            next_tool: "pica_releases_list",
+        },
+        {
+            error_code: "RECORDING_NOT_FOUND",
+            suggestion: "one or more track recording IDs not found",
+            next_tool: "pica_recordings_query",
+        },
+    ],
+    pica_releases_update: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list releases to find the right id",
+            next_tool: "pica_releases_list",
+        },
+    ],
+    pica_releases_attach_track: [
+        {
+            error_code: "RELEASE_NOT_FOUND",
+            suggestion: "list releases to find the right id",
+            next_tool: "pica_releases_list",
+        },
+        {
+            error_code: "RECORDING_NOT_FOUND",
+            suggestion: "search recordings to find the track",
+            next_tool: "pica_recordings_query",
+        },
+    ],
+    pica_releases_attach_track_by_identifier: [
+        {
+            error_code: "NO_MATCH",
+            suggestion: "no recording matched the identifier — import from streaming first",
+            next_tool: "pica_import_streaming_link",
+        },
+    ],
+    pica_releases_attach_recording_with_work: [
+        {
+            error_code: "RELEASE_NOT_FOUND",
+            suggestion: "list releases to find the right id",
+            next_tool: "pica_releases_list",
+        },
+        {
+            error_code: "RECORDING_NOT_FOUND",
+            suggestion: "search recordings to find the track",
+            next_tool: "pica_recordings_query",
+        },
+    ],
+    pica_releases_bulk_attach_tracks: [
+        {
+            error_code: "RELEASE_NOT_FOUND",
+            suggestion: "list releases to find the right id",
+            next_tool: "pica_releases_list",
+        },
+        {
+            error_code: "PARTIAL_NOT_FOUND",
+            suggestion: "some recording IDs not found — verify the track list",
+            next_tool: "pica_recordings_query",
+        },
+    ],
+    pica_releases_detach_track: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list the tracks on this release",
+            next_tool: "pica_releases_list_tracks",
+        },
+    ],
+    pica_releases_move_track: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list the tracks on this release",
+            next_tool: "pica_releases_list_tracks",
+        },
+    ],
+    pica_releases_reorder_tracks: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list the tracks on this release to see the current order",
+            next_tool: "pica_releases_list_tracks",
+        },
+    ],
+    // ── projects ──
+    pica_projects_create: [
+        {
+            error_code: "DUPLICATE_PROJECT",
+            suggestion: "a project with this name already exists",
+            next_tool: "pica_projects_list",
+        },
+    ],
+    pica_projects_update: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your projects to find the right id",
+            next_tool: "pica_projects_list",
+        },
+    ],
+    pica_projects_attach_works: [
+        {
+            error_code: "PROJECT_NOT_FOUND",
+            suggestion: "list your projects to find the right id",
+            next_tool: "pica_projects_list",
+        },
+        {
+            error_code: "PARTIAL_NOT_FOUND",
+            suggestion: "some work IDs not found — search by title",
+            next_tool: "pica_works_query",
+        },
+    ],
+    // ── custody ──
+    pica_custody_claim: [
+        {
+            error_code: "ALREADY_CLAIMED",
+            suggestion: "see the existing custody history for this entity",
+            next_tool: "pica_custody_history",
+        },
+        {
+            error_code: "ENTITY_NOT_FOUND",
+            suggestion: "search for the work or recording first",
+            next_tool: "pica_search_all",
+        },
+    ],
+    pica_custody_respond: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list pending custody claims",
+            next_tool: "pica_custody_list",
+        },
+    ],
+    pica_custody_reconcile: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "see the custody history for this entity",
+            next_tool: "pica_custody_history",
+        },
+    ],
+    pica_claim_credit: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list pending discoveries to find the right id",
+            next_tool: "pica_discoveries_query",
+        },
+    ],
+    pica_claim_custody: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list pending discoveries to find the right id",
+            next_tool: "pica_discoveries_query",
+        },
+    ],
+    pica_claim_artist: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list pending discoveries to find the right id",
+            next_tool: "pica_discoveries_query",
+        },
+    ],
+    // ── enrichment proposals ──
+    pica_enrichment_proposal_apply: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list pending enrichment proposals",
+            next_tool: "pica_enrichment_proposals_list",
+        },
+        {
+            error_code: "DRIFT_DETECTED",
+            suggestion: "the entity changed since the proposal was created — review conflicts and retry with force=true",
+            next_tool: "pica_works_inspect",
+        },
+    ],
+    pica_enrichment_proposal_reject: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list pending enrichment proposals",
+            next_tool: "pica_enrichment_proposals_list",
+        },
+    ],
+    // ── multimedia ──
+    pica_multimedia_link_work: [
+        {
+            error_code: "WORK_NOT_FOUND",
+            suggestion: "search for the work by title",
+            next_tool: "pica_works_query",
+        },
+        {
+            error_code: "MULTIMEDIA_NOT_FOUND",
+            suggestion: "search multimedia to find the right id",
+            next_tool: "pica_multimedia_search",
+        },
+    ],
+    pica_multimedia_link_youtube: [
+        {
+            error_code: "WORK_NOT_FOUND",
+            suggestion: "search for the work by title",
+            next_tool: "pica_works_query",
+        },
+    ],
+    // ── physical assets ──
+    pica_physical_assets_create: [
+        {
+            error_code: "DUPLICATE_ASSET",
+            suggestion: "a similar asset already exists",
+            next_tool: "pica_physical_assets_query",
+        },
+    ],
+    pica_physical_assets_update: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your assets to find the right id",
+            next_tool: "pica_physical_assets_query",
+        },
+    ],
+    pica_physical_assets_link_work: [
+        {
+            error_code: "ASSET_NOT_FOUND",
+            suggestion: "list your assets to find the right id",
+            next_tool: "pica_physical_assets_query",
+        },
+        {
+            error_code: "WORK_NOT_FOUND",
+            suggestion: "search for the work by title",
+            next_tool: "pica_works_query",
+        },
+    ],
+    pica_physical_assets_link_recording: [
+        {
+            error_code: "ASSET_NOT_FOUND",
+            suggestion: "list your assets to find the right id",
+            next_tool: "pica_physical_assets_query",
+        },
+        {
+            error_code: "RECORDING_NOT_FOUND",
+            suggestion: "search recordings to find the right id",
+            next_tool: "pica_recordings_query",
+        },
+    ],
+    pica_physical_assets_unlink_work: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "inspect the asset to see what's currently linked",
+            next_tool: "pica_physical_assets_inspect",
+        },
+    ],
+    pica_physical_assets_unlink_recording: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "inspect the asset to see what's currently linked",
+            next_tool: "pica_physical_assets_inspect",
+        },
+    ],
+    // ── publishers ──
+    pica_publishers_create: [
+        {
+            error_code: "DUPLICATE_PUBLISHER",
+            suggestion: "a publisher with this name already exists",
+            next_tool: "pica_publishers_query",
+        },
+    ],
+    // ── collaborators ──
+    pica_collaborators_invite: [
+        {
+            error_code: "WORK_NOT_FOUND",
+            suggestion: "search for the work by title first",
+            next_tool: "pica_works_query",
+        },
+        {
+            error_code: "DUPLICATE_INVITE",
+            suggestion: "an invite to this email already exists for this work",
+            next_tool: "pica_collaborators_invites_list",
+        },
+    ],
+    pica_collaborators_accept: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list incoming invites to find the right id",
+            next_tool: "pica_collaborators_incoming_list",
+        },
+    ],
+    pica_collaborators_dispute: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list incoming invites to find the right id",
+            next_tool: "pica_collaborators_incoming_list",
+        },
+    ],
+    pica_collaborators_invite_resend: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list outgoing invites to find the right id",
+            next_tool: "pica_collaborators_invites_list",
+        },
+    ],
+    // ── agent identity / grants ──
+    pica_revoke_agent_grant: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your active agent grants",
+            next_tool: "pica_list_my_agent_grants",
+        },
+    ],
+    // ── team ──
+    pica_team_update_role: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list team members to find the right id",
+            next_tool: "pica_team_list",
+        },
+    ],
+    // ── groups (member relationships on people, ADR-223) ──
+    pica_group_add_member: [
+        {
+            error_code: "GROUP_NOT_FOUND",
+            suggestion: "search people for the group person record",
+            next_tool: "pica_people_query",
+        },
+        {
+            error_code: "ALREADY_MEMBER",
+            suggestion: "list members to see the existing membership",
+            next_tool: "pica_group_list_members",
+        },
+    ],
+    pica_group_remove_member: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list members of this group to find active rows",
+            next_tool: "pica_group_list_members",
+        },
+    ],
+    // ── ADR-222 sync placements ──
+    pica_sync_placements_inspect: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "placement id may be wrong — list the org's placements",
+            next_tool: "pica_sync_placements_query",
+        },
+    ],
+    pica_sync_placements_create: [
+        {
+            error_code: "MISSING_CONTACT",
+            suggestion: "at least one contact is required — find existing people or supply a person_name to auto-create",
+            next_tool: "pica_people_query",
+        },
+        {
+            error_code: "INVALID_WORK",
+            suggestion: "the work_id is invalid or not in this org's catalog",
+            next_tool: "pica_works_query",
+        },
+    ],
+    pica_sync_placements_update: [
+        {
+            error_code: "OPERATOR_REQUIRED",
+            suggestion: "this field is operator-only — for self-service retirement use status:'terminated' instead",
+            next_tool: "pica_sync_placements_update",
+        },
+        {
+            error_code: "EVIDENCE_REQUIRED",
+            suggestion: "operator_verified needs at least one document of type sync_contract / cue_sheet / invoice / airing_proof — attach evidence first",
+            next_tool: "pica_documents_create",
+        },
+        {
+            error_code: "INVALID_TRANSITION",
+            suggestion: "this status transition is not allowed by the placement state machine — inspect to see the current status and valid next states",
+            next_tool: "pica_sync_placements_inspect",
+        },
+    ],
+    pica_sync_placements_delete: [
+        {
+            error_code: "OPERATOR_REQUIRED",
+            suggestion: "delete is operator-only — for self-service use update with status:'terminated' (soft-delete)",
+            next_tool: "pica_sync_placements_update",
+        },
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "placement id may be wrong — list the org's placements",
+            next_tool: "pica_sync_placements_query",
+        },
+    ],
+    pica_sync_placements_cite: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "placement id may be wrong — list the org's placements",
+            next_tool: "pica_sync_placements_query",
+        },
+        {
+            error_code: "VALIDATION_ERROR",
+            suggestion: "inspect the placement to see the source schema and required fields before retrying",
+            next_tool: "pica_sync_placements_inspect",
+        },
+    ],
+};
+/**
+ * Tools that are intentionally NOT in `RECOVERY_HINTS` despite being
+ * `mutating` or `destructive`. Read by the lint at
+ * `scripts/lint-mcp-tools.ts` (ADR-180 Rule 10) — every mutating/
+ * destructive tool must either appear in `RECOVERY_HINTS` or here.
+ *
+ * Three buckets:
+ *
+ *   `rich_response`: returns a structured response shape that already
+ *   carries the "what next" affordance. The resolver tools populate
+ *   `recovery_hints: string[]` on the response itself; import/export
+ *   tools return a structured download envelope; cascade runners are
+ *   fire-and-forget; the upload pair returns presigned-URL state.
+ *
+ *   `terminal`: no plausible recovery. One-shot tools, idempotent acks,
+ *   or validation-only writes whose only failure mode is a clear schema
+ *   error the agent can fix from the error message alone.
+ *
+ *   `dispatcher`: discriminated-branch tool that is a renaming candidate
+ *   per the agreement-types audit. Adding hints to the dispatcher would
+ *   be wasted work if the tools split.
+ *
+ * If a tool is added to `RECOVERY_HINTS`, remove it from here. The lint
+ * emits a stale-skip warning when both are populated for the same tool.
+ */
+export const INTENTIONALLY_SKIPPED = new Map([
+    // rich_response
+    ["pica_resolve_work", "rich_response"],
+    ["pica_resolve_person", "rich_response"],
+    ["pica_resolve_recording", "rich_response"],
+    ["pica_run_work_cascade", "rich_response"],
+    ["pica_run_person_cascade", "rich_response"],
+    ["pica_audio_analyze", "rich_response"],
+    ["pica_audio_complete_upload", "rich_response"],
+    ["pica_audio_presigned_upload", "rich_response"],
+    ["pica_documents_analyse", "rich_response"],
+    ["pica_enrichment_propose", "rich_response"],
+    ["pica_export_ai_consent", "rich_response"],
+    ["pica_export_catalog_asset_report", "rich_response"],
+    ["pica_export_industry_ready", "rich_response"],
+    ["pica_export_my_data", "rich_response"],
+    ["pica_export_song_registration", "rich_response"],
+    ["pica_ingest_statement", "rich_response"],
+    ["pica_report_issue", "rich_response"],
+    ["pica_send_message", "rich_response"],
+    ["pica_send_resend", "rich_response"],
+    ["pica_subscription_manage", "rich_response"],
+    ["pica_upload_complete", "rich_response"],
+    ["pica_upload_file", "rich_response"],
+    ["pica_collaborators_invite_bulk", "rich_response"],
+    ["pica_discoveries_review", "rich_response"],
+    ["pica_multimedia_create", "rich_response"],
+    ["pica_multimedia_import_url", "rich_response"],
+    // terminal
+    ["pica_acknowledge_onboarding", "terminal"],
+    ["pica_delete_my_account", "terminal"],
+    ["pica_notification_acknowledge", "terminal"],
+    ["pica_notifications_mark_read", "terminal"],
+    ["pica_notify_user", "terminal"],
+    ["pica_notify_user_at", "terminal"],
+    ["pica_notify_user_cancel", "terminal"],
+    ["pica_provenance_certificate", "terminal"],
+    ["pica_sessions_create", "terminal"],
+    ["pica_share_links_create", "terminal"],
+    ["pica_share_links_delete", "terminal"],
+    ["pica_share_links_update", "terminal"],
+    ["pica_split_sheet_send", "terminal"],
+    ["pica_storage_disconnect", "terminal"],
+    ["pica_submit_feedback", "terminal"],
+    ["pica_submit_license_enquiry", "terminal"],
+    ["pica_telegram_connect", "terminal"],
+    ["pica_update_license_enquiry_status", "terminal"],
+    ["pica_update_my_identity", "terminal"],
+    ["pica_update_organisation_profile", "terminal"],
+    ["pica_update_privacy_settings", "terminal"],
+    ["pica_works_verify", "terminal"],
+    ["pica_memory_save", "terminal"],
+    ["pica_notes_create", "terminal"],
+    ["pica_team_invite", "terminal"],
+    ["pica_create_agent_identity", "terminal"],
+    ["pica_issue_agent_grant", "terminal"],
+    // dispatcher
+    ["pica_agreement_types_create", "dispatcher"],
+    ["pica_agreement_types_update", "dispatcher"],
+    ["pica_agreement_types_delete", "dispatcher"],
+]);
+export function getRecoveryHint(toolName, errorCode) {
+    const hints = RECOVERY_HINTS[toolName];
+    if (!hints)
+        return undefined;
+    return hints.find((h) => h.error_code === errorCode);
+}
+//# sourceMappingURL=recovery-hints.js.map