@withpica/mcp-server 1.3.0

package/dist/tools/index.js

@@ -0,0 +1,1182 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { WorksTools } from "./works.js";
+import { PeopleTools } from "./people.js";
+import { GroupsTools } from "./groups.js";
+import { RecordingsTools } from "./recordings.js";
+import { SearchTools } from "./search.js";
+import { LicensingTools } from "./licensing.js";
+import { CreditsTools } from "./credits.js";
+import { AudioFilesTools } from "./audio-files.js";
+import { MultimediaTools } from "./multimedia.js";
+import { AgreementsTools } from "./agreements.js";
+import { MemoryTools } from "./memory.js";
+import { EnrichmentTools } from "./enrichment.js";
+import { BulkTools } from "./bulk.js";
+import { ExportTools } from "./exports.js";
+import { DuplicatesTools, coerceMergeEntityType } from "./duplicates.js";
+import { DirectoryTools } from "./directory.js";
+import { CollaboratorsTools } from "./collaborators.js";
+import { ImportDocumentTools } from "./import-documents.js";
+import { UploadTools } from "./uploads.js";
+import { DocumentTools } from "./documents.js";
+import { ImportTools } from "./import.js";
+import { SendTools } from "./send.js";
+import { ComparisonTools } from "./comparisons.js";
+import { AssetsTools } from "./assets.js";
+import { SessionsTools } from "./sessions.js";
+import { AnalyticsTools } from "./analytics.js";
+import { NotificationsTools } from "./notifications.js";
+import { NotesTools } from "./notes.js";
+import { TeamTools } from "./team.js";
+import { ProjectsTools } from "./projects.js";
+import { ReleasesTools } from "./releases.js";
+import { ReleaseRichTools } from "./release-rich.js";
+import { CalendarTools } from "./calendar.js";
+import { SplitSheetsTools } from "./split-sheets.js";
+import { AgreementTypesTools } from "./agreement-types.js";
+import { DashboardTools } from "./dashboard.js";
+import { IntegrationsTools } from "./integrations.js";
+import { SettingsTools } from "./settings.js";
+import { FeedbackTools } from "./feedback.js";
+import { StorageConfigTools } from "./storage-config.js";
+import { SubscriptionTools } from "./subscription.js";
+import { OnboardingTools } from "./onboarding.js";
+import { ReportIssueTools } from "./report-issue.js";
+import { MyReportedIssuesTools } from "./my-reported-issues.js";
+import { AgentIdentityTools } from "./agent-identity.js";
+import { RoyaltiesTools } from "./royalties.js";
+import { ShareLinksTools } from "./share-links.js";
+import { DisputesTools } from "./disputes.js";
+import { CustodyTools } from "./custody.js";
+import { PurchasesTools } from "./purchases.js";
+import { TelegramTools } from "./telegram.js";
+import { PublishersTools } from "./publishers.js";
+import { LabelsTools } from "./labels.js";
+import { AuthTools } from "./auth.js";
+import { SignupTools } from "./signup.js";
+import { AppTools } from "./app-tools.js";
+import { AuditTools } from "./audit.js";
+import { DiscoveryTools } from "./discovery.js";
+import { SyncPlacementsTools } from "./sync-placements.js";
+import { readCredentials } from "@withpica/mcp-utils";
+import { formatError, ToolExecutionError } from "@withpica/mcp-utils";
+import { guardResponseSize } from "@withpica/mcp-utils";
+import { getToolMetadata } from "./metadata.js";
+import { getRecoveryHint } from "./recovery-hints.js";
+import { generateConfirmationToken, validateAndConsumeToken, } from "@withpica/mcp-utils";
+import { buildSessionState, incrementSessionMutations, resetSinceLastBriefing, } from "@withpica/mcp-utils";
+/**
+ * Build a tool description with metadata injected.
+ * Format: "[category] original description"
+ */
+export function injectMetadataIntoDescription(description, metadata) {
+    // Category tag helps the agent understand tool grouping.
+    // Risk prefixes removed — annotations (readOnlyHint, destructiveHint) handle this structurally.
+    // Behavioral guidance (tell user what you're doing) is in server instructions (one copy).
+    return `[${metadata.category}] ${description}`;
+}
+export const CATEGORY_DISPLAY = {
+    catalog: "manage your catalog",
+    enrichment: "enrich your metadata",
+    business: "handle business and agreements",
+    discovery: "search and explore",
+    media: "manage photos, audio, and video",
+    comms: "send and share",
+    settings: "manage your account and team",
+};
+export class ToolRegistry {
+    tools;
+    pica;
+    config;
+    reinitializeCallback;
+    signOutCallback;
+    auditLogger;
+    callerContext;
+    constructor(pica, config, reinitializeCallback, callerContext, signOutCallback) {
+        this.pica = pica;
+        this.config = config;
+        this.reinitializeCallback = reinitializeCallback;
+        this.signOutCallback = signOutCallback;
+        this.callerContext = callerContext ?? {
+            callerIdentity: "unknown",
+            transport: "stdio",
+        };
+        this.tools = new Map();
+        this.registerAllTools();
+    }
+    setAuditLogger(logger) {
+        this.auditLogger = logger;
+    }
+    setCallerContext(context) {
+        this.callerContext = context;
+    }
+    /**
+     * Register all available tools
+     */
+    registerAllTools() {
+        // Auth tools — always registered (lobby + authenticated mode)
+        if (this.config) {
+            const authTools = new AuthTools(this.config, this.reinitializeCallback || (() => { }), this.signOutCallback || (() => { }));
+            authTools.getTools().forEach((tool) => {
+                this.tools.set(tool.definition.name, tool);
+            });
+            // ADR-211 P1 — Signup tool. Registered in lobby alongside the auth
+            // pair so unauthenticated callers (stdio without API key, HTTP
+            // without Bearer) have a discoverable signup verb. Stays registered
+            // post-auth too — the tool itself is harmless once you're signed in
+            // (mints a link for a new account, not your existing one) and that
+            // matches the ADR-211 § Primitive A 2026-04-30 amendment which
+            // makes Phase 1 lobby additive (3 tools), not replacement.
+            //
+            // Transport is read from callerContext so stdio + HTTP transports
+            // stamp their JWTs correctly without per-call config plumbing.
+            const signupTools = new SignupTools({
+                apiUrl: this.config.picaApiUrl,
+                transport: this.callerContext.transport,
+            });
+            signupTools.getTools().forEach((tool) => {
+                this.tools.set(tool.definition.name, tool);
+            });
+        }
+        // In lobby mode, only auth + signup tools are available
+        if (this.config?.lobbyMode || !this.pica) {
+            return;
+        }
+        const pica = this.pica;
+        // Works tools
+        const worksTools = new WorksTools(pica);
+        worksTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // People tools
+        const peopleTools = new PeopleTools(pica);
+        peopleTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Groups tools (ADR-223)
+        const groupsTools = new GroupsTools(pica);
+        groupsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Recordings tools
+        const recordingsTools = new RecordingsTools(pica);
+        recordingsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Search tools
+        const searchTools = new SearchTools(pica);
+        searchTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Licensing tools
+        const licensingTools = new LicensingTools(pica);
+        licensingTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Credits tools
+        const creditsTools = new CreditsTools(pica);
+        creditsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Audio Files tools
+        const audioFilesTools = new AudioFilesTools(pica);
+        audioFilesTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Multimedia tools
+        const multimediaTools = new MultimediaTools(pica);
+        multimediaTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Agreements tools
+        const agreementsTools = new AgreementsTools(pica);
+        agreementsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Memory tools
+        const memoryTools = new MemoryTools(pica);
+        memoryTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Enrichment tools
+        const enrichmentTools = new EnrichmentTools(pica);
+        enrichmentTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Bulk operations tools
+        const bulkTools = new BulkTools(pica);
+        bulkTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Export tools
+        const exportTools = new ExportTools(pica);
+        exportTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Duplicates tools
+        const duplicatesTools = new DuplicatesTools(pica);
+        duplicatesTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Directory tools
+        const directoryTools = new DirectoryTools(pica);
+        directoryTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Collaborator tools
+        const collaboratorsTools = new CollaboratorsTools(pica);
+        collaboratorsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Upload tools (generic file upload — images, videos, documents)
+        const uploadTools = new UploadTools(pica);
+        uploadTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Document tools (AI analysis)
+        const documentTools = new DocumentTools(pica);
+        documentTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Bulk import tools (CSV import pipeline)
+        const importTools = new ImportTools(pica);
+        importTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Comparison tools (ADR-116 Phase 2: enrichment + registration comparison)
+        const comparisonTools = new ComparisonTools(pica);
+        comparisonTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Send Hub tools (messages, invites, file requests, audio shares)
+        const sendTools = new SendTools(pica);
+        sendTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Import document tools
+        const importDocumentTools = new ImportDocumentTools(pica);
+        importDocumentTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Physical assets tools (equipment, instruments, studio gear)
+        const assetsTools = new AssetsTools(pica);
+        assetsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Work sessions tools (studio session tracking)
+        const sessionsTools = new SessionsTools(pica);
+        sessionsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Analytics tools (carbon, provenance, diligence)
+        const analyticsTools = new AnalyticsTools(pica);
+        analyticsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Notifications tools
+        const notificationsTools = new NotificationsTools(pica);
+        notificationsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Notes tools (catalog notes on works, people, general observations)
+        const notesTools = new NotesTools(pica);
+        notesTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Team management tools (invite, list, update, remove members)
+        const teamTools = new TeamTools(pica);
+        teamTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Projects tools (albums, EPs, compilations — grouping works)
+        const projectsTools = new ProjectsTools(pica);
+        projectsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Releases tools (albums, EPs, singles with dates, labels, UPCs)
+        const releasesTools = new ReleasesTools(pica);
+        releasesTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // ADR-208 Phase 3 Primitive D — release rich render (image + markdown)
+        const releaseRichTools = new ReleaseRichTools(pica);
+        releaseRichTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Calendar tools
+        const calendarTools = new CalendarTools(pica);
+        calendarTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Split sheets & recording splits tools
+        const splitSheetsTools = new SplitSheetsTools(pica);
+        splitSheetsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Agreement types tools (templates, producer agreements, work-for-hire)
+        const agreementTypesTools = new AgreementTypesTools(pica);
+        agreementTypesTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Dashboard & discovery tools
+        const dashboardTools = new DashboardTools(pica);
+        dashboardTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Integrations tools (connection status)
+        const integrationsTools = new IntegrationsTools(pica);
+        integrationsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Settings tools (credits history, storage, org profile)
+        const settingsTools = new SettingsTools(pica);
+        settingsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Feedback tools (ADR-184 slice 8 — pica_submit_feedback)
+        const feedbackTools = new FeedbackTools(pica);
+        feedbackTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Storage config tools (ADR-217 — Primitives B + C; Primitive A
+        // pica_storage_status lives in settings.ts because it shipped earlier
+        // alongside the original settings cluster).
+        const storageConfigTools = new StorageConfigTools(pica);
+        storageConfigTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Subscription tools (ADR-210 Phase 2 — pica_subscription_status +
+        // pica_subscription_manage). Explicit billing read + action surface
+        // complementing the ambient _meta.session_state.billing_slice from
+        // Phase 1.
+        const subscriptionTools = new SubscriptionTools(pica);
+        subscriptionTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Onboarding tools — pica_acknowledge_onboarding gates OAuth-arrived
+        // users until the agent walks them through identity/security/intent.
+        const onboardingTools = new OnboardingTools(pica);
+        onboardingTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Report-issue tool (ADR-196 Phase 3 — pica_report_issue)
+        const reportIssueTools = new ReportIssueTools(pica);
+        reportIssueTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // My-reported-issues tool (ADR-196 Phase 4a — pica_my_reported_issues)
+        // — closed-loop counterpart to pica_report_issue. Org-scoped polling.
+        const myReportedIssuesTools = new MyReportedIssuesTools(pica);
+        myReportedIssuesTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Agent identity tools (ADR-185 Part 1 — session-auth-only MCP surface).
+        // The three tools refuse grant-auth callers at the HTTP API layer;
+        // the stdio path carries an API key so behaviour is identical either
+        // way.
+        const agentIdentityTools = new AgentIdentityTools(pica);
+        agentIdentityTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Royalties & statements tools (ADR-139 Step 2)
+        const royaltiesTools = new RoyaltiesTools(pica);
+        royaltiesTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Share links tools (ADR-139 Step 3)
+        const shareLinksTools = new ShareLinksTools(pica);
+        shareLinksTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Disputes tools (ADR-139 Step 3)
+        const disputesTools = new DisputesTools(pica);
+        disputesTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Custody tools (ADR-158 Plan C)
+        const custodyTools = new CustodyTools(pica);
+        custodyTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Purchases tools (credit checkout)
+        const purchasesTools = new PurchasesTools(pica);
+        purchasesTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Telegram tools (user notification channel)
+        const telegramTools = new TelegramTools(pica);
+        telegramTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Publishers tools (lookup + create)
+        const publishersTools = new PublishersTools(pica);
+        publishersTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Labels tools (read-only lookup; ADR-174 Decision 3)
+        const labelsTools = new LabelsTools(pica);
+        labelsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // App tools (MCP Apps — interactive UI cards)
+        const appTools = new AppTools(pica);
+        appTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Audit tools (recent MCP tool executions — ADR-154 F6)
+        // ADR-181 Phase 1: ported from the (now-retired)
+        // @withpica/mcp-server-settings sub-server as part of the customer
+        // MCP surface consolidation. The sub-server was the only place this
+        // tool shipped before consolidation; every other sub-server tool
+        // already existed in mcp-server/ so only pica_audit_list had to move.
+        // Phase 3 (2026-04-19) tombstoned the sub-package on npm + registry
+        // and deleted the source tree.
+        const auditTools = new AuditTools(pica);
+        auditTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // ADR-222 sync placements
+        const syncPlacementsTools = new SyncPlacementsTools(pica);
+        syncPlacementsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Discovery meta-tools — registered last so pica_tool_details can look up
+        // all tool definitions. Only active when discoveryMode is enabled.
+        if (this.config?.discoveryMode) {
+            const discoveryTools = new DiscoveryTools((name, args, ctx) => this.executeTool(name, args, ctx), (name) => this.tools.get(name));
+            discoveryTools.getTools().forEach((tool) => {
+                this.tools.set(tool.definition.name, tool);
+            });
+        }
+    }
+    // ── Write-safety classification ──
+    // Destructive tools require confirmation before AND summary after.
+    // Mutating tools should present what they'll do and confirm after.
+    // Safe (read-only) tools need no confirmation.
+    static DESTRUCTIVE_PATTERNS = [
+        "_delete",
+        "_bulk_delete",
+        "_merge",
+        "_remove",
+        "_disconnect",
+    ];
+    static MUTATING_PATTERNS = [
+        "_create",
+        "_update",
+        "_bulk_update",
+        "_invite",
+        "_link",
+        "_send_",
+        "_import_",
+        "_execute",
+        "_ingest",
+        "_enrich",
+        "_verify",
+        "_mark_",
+        "_review",
+        "_purchase",
+        "_submit",
+        "_generate",
+        "_set_default",
+        "_duplicate",
+        "_toggle",
+        "_save",
+        "_upload",
+        "_complete",
+        "_analyze",
+        "_analyse",
+        "_identify",
+        "_resend",
+        "_notify",
+    ];
+    // Read-only tools that match mutating patterns by name but are actually safe
+    static SAFE_OVERRIDES = new Set([
+        "pica_collaborators_invites_list",
+        "pica_enrichment_candidates",
+        "pica_enrichment_compare",
+        "pica_find_duplicates",
+        "pica_import_analyze",
+        "pica_import_validate",
+        "pica_import_fields",
+        "pica_import_template",
+        "pica_import_documents_query",
+        "pica_import_documents_inspect",
+        "pica_send_query",
+        "pica_share_links_list",
+    ]);
+    classifyTool(name) {
+        if (ToolRegistry.SAFE_OVERRIDES.has(name)) {
+            return "safe";
+        }
+        if (ToolRegistry.DESTRUCTIVE_PATTERNS.some((p) => name.includes(p))) {
+            return "destructive";
+        }
+        if (ToolRegistry.MUTATING_PATTERNS.some((p) => name.includes(p))) {
+            return "mutating";
+        }
+        return "safe";
+    }
+    /**
+     * List all available tools with write-safety prefixes injected.
+     * When discoveryMode is enabled, only the 5 handshake-visible tools are returned.
+     * All other tools remain registered and callable via pica_execute.
+     */
+    listTools() {
+        let toolsToList = Array.from(this.tools.values());
+        if (this.config?.discoveryMode) {
+            const META_TOOL_NAMES = new Set([
+                "pica_sign_in",
+                "pica_sign_out",
+                "pica_discover",
+                "pica_tool_details",
+                "pica_execute",
+            ]);
+            toolsToList = toolsToList.filter((t) => META_TOOL_NAMES.has(t.definition.name));
+        }
+        return toolsToList.map((tool) => {
+            let definition = tool.definition;
+            const metadata = getToolMetadata(definition.name);
+            // Inject confirmation_token into destructive tool schemas
+            const isDestructive = metadata?.risk === "destructive" ||
+                (!metadata && this.classifyTool(definition.name) === "destructive");
+            if (isDestructive) {
+                definition = {
+                    ...definition,
+                    inputSchema: {
+                        ...definition.inputSchema,
+                        properties: {
+                            ...definition.inputSchema.properties,
+                            confirmation_token: {
+                                type: "string",
+                                description: "Confirmation token from a previous call. Required to execute destructive operations. " +
+                                    "Call this tool once without a token to get a preview and token, then call again with the token to confirm.",
+                            },
+                        },
+                    },
+                };
+            }
+            // Normalize _meta.ui.resourceUri → legacy "ui/resourceUri" key for older MCP Apps clients
+            if (definition._meta?.ui?.resourceUri &&
+                !definition._meta["ui/resourceUri"]) {
+                definition = {
+                    ...definition,
+                    _meta: {
+                        ...definition._meta,
+                        "ui/resourceUri": definition._meta.ui.resourceUri,
+                    },
+                };
+            }
+            if (metadata) {
+                return {
+                    ...definition,
+                    description: injectMetadataIntoDescription(tool.definition.description, metadata),
+                    annotations: {
+                        title: metadata.display_name,
+                        readOnlyHint: metadata.risk === "safe",
+                        destructiveHint: metadata.risk === "destructive",
+                        idempotentHint: metadata.risk !== "destructive" && metadata.retry_safe,
+                        openWorldHint: false,
+                        // ADR-199 extended annotation classes — read by ChatGPT/Claude.ai
+                        // connectors directly. Derived from existing metadata so existing
+                        // tools get this for free without per-tool edits.
+                        ...this.deriveExtendedAnnotations(definition, metadata),
+                    },
+                };
+            }
+            // Fallback to old pattern-matching for any tool without explicit metadata
+            const classification = this.classifyTool(definition.name);
+            const annotations = {
+                title: definition.name,
+                readOnlyHint: classification === "safe",
+                destructiveHint: classification === "destructive",
+                idempotentHint: false,
+                openWorldHint: false,
+                // ADR-199: derive the extended classes even without explicit
+                // metadata so the fallback tools also surface category/risk to
+                // ChatGPT/Claude.ai connectors.
+                ...this.deriveExtendedAnnotations(definition, null, classification),
+            };
+            // No risk prefix needed — annotations handle this structurally
+            return { ...definition, annotations };
+        });
+    }
+    /**
+     * ADR-199 — derive the extended annotation classes (riskLevel, category,
+     * requiresConfirmation, createsExternalSideEffects, returnsPaginated,
+     * requiresFollowUpInspection) from existing metadata + tool name patterns.
+     *
+     * Called from listTools() for every tool. Pure derivation: zero per-tool
+     * edits required for the retrofit. Future tool authors can override by
+     * setting fields directly on definition.annotations.
+     */
+    deriveExtendedAnnotations(definition, metadata, classification) {
+        const name = definition.name;
+        const risk = metadata?.risk ?? classification ?? "safe";
+        // Side-effecting external systems: telegram, send-hub, comms, broadcasts.
+        // Pattern-derived so new tools inherit without edits.
+        const externalSideEffectPatterns = [
+            "telegram",
+            "_send_",
+            "_send",
+            "send_message",
+            "send_resend",
+            "team_comms_send",
+            "_notify_user",
+            "_invite",
+        ];
+        const createsExternalSideEffects = externalSideEffectPatterns.some((p) => name.includes(p));
+        // Paginated reads: every *_query and *_list tool.
+        const returnsPaginated = /_query$|_list$|_search/.test(name);
+        // Tools that mutate state are followed by a verifying inspect call when
+        // the agent wants to confirm — the gap report flagged this as a useful
+        // class for ChatGPT to surface in the UI.
+        const requiresFollowUpInspection = risk === "mutating" || risk === "destructive";
+        return {
+            riskLevel: risk,
+            category: metadata?.category,
+            requiresConfirmation: risk === "destructive",
+            createsExternalSideEffects,
+            returnsPaginated,
+            requiresFollowUpInspection,
+        };
+    }
+    /**
+     * Build a human-readable preview of what a destructive operation will affect.
+     */
+    async buildDestructivePreview(name, args) {
+        const metadata = getToolMetadata(name);
+        const displayName = metadata?.display_name || name;
+        // buildDestructivePreview is only called during tool execution,
+        // which is gated behind lobby mode check — pica is always available here.
+        const pica = this.pica;
+        try {
+            switch (name) {
+                case "pica_works_delete": {
+                    const work = await pica.works.get(args.id).catch(() => null);
+                    const title = work?.title || args.id;
+                    return {
+                        action: "delete work",
+                        target: title,
+                        warning: "this will remove linked credits, agreement links, and audio files. recordings will be unlinked. this cannot be undone for works without verified identifiers.",
+                        display_name: displayName,
+                    };
+                }
+                case "pica_works_bulk_delete": {
+                    const count = args.ids?.length || 0;
+                    return {
+                        action: "bulk delete works",
+                        target: `${count} works`,
+                        warning: `this will delete ${count} work(s) and cascade to their credits and agreement links. this cannot be undone for works without verified identifiers.`,
+                        display_name: displayName,
+                    };
+                }
+                case "pica_people_delete": {
+                    const person = await pica.people.get(args.id).catch(() => null);
+                    const personName = person?.first_name
+                        ? `${person.first_name} ${person.last_name || ""}`.trim()
+                        : args.id;
+                    return {
+                        action: "remove person",
+                        target: personName,
+                        warning: "the person record will be soft-deleted. credits and agreements will remain linked.",
+                        display_name: displayName,
+                    };
+                }
+                case "pica_agreements_delete": {
+                    const agreementResult = await pica.agreements
+                        .get(args.id)
+                        .catch(() => null);
+                    const title = agreementResult?.agreement?.title || args.id;
+                    return {
+                        action: "delete agreement",
+                        target: title,
+                        warning: "this will remove all linked work and party records. this cannot be undone.",
+                        display_name: displayName,
+                    };
+                }
+                case "pica_merge_duplicates": {
+                    const loserCount = args.loser_ids?.length || 0;
+                    let entityType = "entities";
+                    try {
+                        entityType = coerceMergeEntityType(args.entity_type).canonical;
+                    }
+                    catch {
+                        // Unknown entity_type — fall back to generic noun in the warning
+                        // copy. Tool execution itself will surface the validation error.
+                    }
+                    return {
+                        action: `merge ${entityType}`,
+                        target: `${loserCount} ${entityType} into winner`,
+                        warning: `all credits, recordings, and agreements from ${loserCount} loser(s) will be moved to the winner. loser records will be permanently deleted. this cannot be undone.`,
+                        display_name: displayName,
+                    };
+                }
+                case "pica_projects_delete": {
+                    const project = await pica.projects?.get(args.id).catch(() => null);
+                    const projectName = project?.name || args.id;
+                    return {
+                        action: "delete project",
+                        target: projectName,
+                        warning: "linked works will be unlinked but not deleted. this cannot be undone.",
+                        display_name: displayName,
+                    };
+                }
+                case "pica_team_remove": {
+                    return {
+                        action: "remove team member",
+                        target: args.id,
+                        warning: "their user account will be permanently deleted. works and agreements they contributed will remain. this cannot be undone.",
+                        display_name: displayName,
+                    };
+                }
+                // ── ADR-199 Stream 5b — 7 fall-through cases now specific ──
+                case "pica_recordings_delete": {
+                    const recording = await pica.recordings
+                        ?.get?.(args.id)
+                        .catch(() => null);
+                    const title = recording?.title || args.id;
+                    const isrc = recording?.isrc;
+                    return {
+                        action: "delete recording",
+                        target: isrc ? `${title} (${isrc})` : title,
+                        warning: "the recording will be removed from its work and any release. credits attached to this recording will be detached. this cannot be undone.",
+                        display_name: displayName,
+                    };
+                }
+                case "pica_share_links_delete": {
+                    const link = await pica.shareLinks.get(args.id).catch(() => null);
+                    const linkData = link?.data || link;
+                    const linkName = linkData?.name || args.id;
+                    return {
+                        action: "delete share link",
+                        target: linkName,
+                        warning: "the link will become inaccessible immediately. recipients with the URL will see a 'no longer available' page. view / download history is removed. to keep the audit trail, prefer pica_share_links_update with is_active=false.",
+                        display_name: displayName,
+                    };
+                }
+                case "pica_agreement_types_delete": {
+                    return {
+                        action: "delete agreement type",
+                        target: args.id,
+                        warning: "the agreement type will be removed from the catalog. existing agreements that reference this type will keep their type string but lose the template definition. this cannot be undone.",
+                        display_name: displayName,
+                    };
+                }
+                case "pica_notes_delete": {
+                    return {
+                        action: "delete note",
+                        target: args.id,
+                        warning: "the note will be permanently removed. attachments referenced by the note are not deleted. this cannot be undone.",
+                        display_name: displayName,
+                    };
+                }
+                case "pica_physical_assets_delete": {
+                    const asset = await pica.physicalAssets
+                        ?.get?.(args.id)
+                        .catch(() => null);
+                    const assetName = asset?.name || asset?.title || args.id;
+                    return {
+                        action: "delete physical asset",
+                        target: assetName,
+                        warning: "the asset record and any linked recording / work associations will be removed. this cannot be undone — re-create from scratch if you need it back.",
+                        display_name: displayName,
+                    };
+                }
+                case "pica_memory_delete": {
+                    return {
+                        action: "delete memory entry",
+                        target: args.id,
+                        warning: "the memory entry will be permanently removed and will not appear in future agent context. this cannot be undone.",
+                        display_name: displayName,
+                    };
+                }
+                case "pica_delete_my_account": {
+                    return {
+                        action: "delete account",
+                        target: "your account and organisation",
+                        warning: "this is permanent. your auth user, organisation membership, API keys, OAuth tokens, agent grants, and notification preferences will all be removed. catalog data (works, recordings, credits) is retained per data-retention policy. this cannot be undone.",
+                        display_name: displayName,
+                    };
+                }
+                case "pica_revoke_agent_grant": {
+                    const grantId = args.grant_id || args.id;
+                    return {
+                        action: "revoke agent grant",
+                        target: grantId,
+                        warning: "the grant token will stop authenticating immediately. any in-flight agent calls using this grant will fail at next request. this cannot be undone — issue a new grant if needed.",
+                        display_name: displayName,
+                    };
+                }
+                default: {
+                    return {
+                        action: displayName,
+                        target: args.id || "unknown",
+                        warning: "this cannot be undone.",
+                        display_name: displayName,
+                    };
+                }
+            }
+        }
+        catch {
+            return {
+                action: displayName,
+                target: args.id || "unknown",
+                warning: "this cannot be undone.",
+                display_name: displayName,
+            };
+        }
+    }
+    /**
+     * Sanitize tool parameters for audit logging.
+     * Strips confirmation tokens and truncates large string values.
+     */
+    sanitizeParams(args) {
+        const sanitized = { ...args };
+        delete sanitized.confirmation_token;
+        for (const [key, value] of Object.entries(sanitized)) {
+            if (typeof value === "string" && value.length > 500) {
+                sanitized[key] = value.substring(0, 500) + "...[truncated]";
+            }
+        }
+        return sanitized;
+    }
+    /**
+     * ADR-208 Primitive B — opaque per-org cache key.
+     *
+     * Stdio: `config.picaApiKey` is the org-bound API key from credentials,
+     * unique per org. HTTP non-discovery: `callerContext.callerIdentity` is
+     * `http:${authContext.keyId}` set by `app/api/mcp/route.ts`, also unique
+     * per org. This is the cross-org cache isolation invariant required by
+     * acceptance criterion 4 — two orgs sharing a worker process never share
+     * a cacheKey. Returns `null` (and the wrapper skips session_state) when
+     * neither identifier is present.
+     */
+    getSessionCacheKey() {
+        const apiKey = this.config?.picaApiKey;
+        if (apiKey)
+            return apiKey;
+        if (this.callerContext.callerIdentity &&
+            this.callerContext.callerIdentity !== "unknown") {
+            return this.callerContext.callerIdentity;
+        }
+        return null;
+    }
+    /**
+     * ADR-208 Primitive B + ADR-208 Phase 2 + ADR-210 Phase 1 — fetch the
+     * org-scoped counts + billing slice via `pica.catalogStats()`. The
+     * endpoint composes the billing slice server-side via
+     * `subscriptionService.getOrgBillingSlice` and the pending-uploads count
+     * via the new `organisations.pending_uploads_count` column so stdio +
+     * HTTP transports stay symmetric.
+     *
+     * `completeness_pct` is stubbed at 0 in Phase 1 and will be wired in a
+     * Phase 1.5 follow-up. The stub keeps the shape contract green without
+     * forcing a separate endpoint extension into this PR.
+     *
+     * Fail-soft: when `this.pica` is missing (HTTP-discovery without bearer
+     * scope, mostly), every count is 0 and the billing slice falls back to
+     * a conservative "trial" shape so the agent doesn't see misleading
+     * "active" billing for an uninitialized context.
+     */
+    fetchSessionCounts = async () => {
+        if (!this.pica) {
+            return {
+                works_count: 0,
+                recordings_count: 0,
+                completeness_pct: 0,
+                pending_uploads: 0,
+                billing_state: "trial",
+                trial_days_remaining: null,
+                current_tier: null,
+                capacity_pct: 0,
+            };
+        }
+        const stats = await this.pica.catalogStats();
+        const billing = stats.billing_slice;
+        // ADR-217 Primitive D — storage slice from /api/admin/catalog/stats.
+        // Optional in the response so older servers without ADR-217 keep
+        // working — when missing, omit the key entirely (vs fabricating a
+        // misleading "pica_s3 / untested" envelope that would suppress an
+        // agent's "you might want to configure storage" nudge).
+        const storage = stats.storage_slice;
+        const counts = {
+            works_count: stats.works?.total ?? 0,
+            recordings_count: stats.recordings?.total ?? 0,
+            // Phase 1.5 stub — completeness_pct ships separately. Shape preserved.
+            completeness_pct: 0,
+            pending_uploads: stats.pending_uploads_count ?? 0,
+            // ADR-210 Phase 1 — billing slice from /api/admin/catalog/stats. The
+            // endpoint emits a "trial" fallback on its own billing-side outage; if
+            // the field is missing entirely (older server pre-Phase-1), mirror the
+            // same conservative shape locally rather than fabricate "active".
+            billing_state: billing?.billing_state ?? "trial",
+            trial_days_remaining: billing?.trial_days_remaining ?? null,
+            current_tier: billing?.current_tier ?? null,
+            capacity_pct: billing?.capacity_pct ?? 0,
+            ...(storage
+                ? {
+                    storage_provider: {
+                        provider: storage.provider,
+                        is_byoc: storage.is_byoc,
+                        last_test_status: storage.last_test_status,
+                    },
+                }
+                : {}),
+        };
+        // ADR-218 Primitive A — propagate the optional notifications summary
+        // when the catalog-stats response carries it. Older API servers
+        // (pre-ADR-218) omit the field; we leave the envelope key off in that
+        // case so the agent doesn't see a fabricated zero.
+        if (stats.notifications) {
+            counts.notifications = stats.notifications;
+        }
+        return counts;
+    };
+    /**
+     * P3c — attach `_meta.schemas` (workflow-resource URIs) to a successful
+     * workflow-tagged tool result. Mirrors `attachSessionState`'s merge
+     * semantics: spread existing `_meta`, add the new key, leave other
+     * keys (e.g. `session_state`) untouched.
+     *
+     * Applies to ALL workflow-tagged tools (Option X), including read
+     * companions like `pica_sessions_list`, so the agent gets the schema
+     * pointer no matter which verb they hit first. Skips when:
+     *  - the tool's `workflows` is or contains only `"infrastructure"`
+     *    (no schema resource exists), or
+     *  - the result is an error (the workflow didn't progress).
+     *
+     * Fail-open like `attachSessionState`: derivation is pure today, but
+     * any future throw must not turn a successful tool result into a
+     * failure.
+     */
+    attachSchemaHints(result, workflows) {
+        try {
+            const tags = Array.isArray(workflows) ? workflows : [workflows];
+            const schemas = tags
+                .filter((t) => t !== "infrastructure")
+                .map((t) => `pica://schemas/${t}`);
+            if (schemas.length === 0)
+                return;
+            const existingMeta = result._meta ?? {};
+            result._meta = {
+                ...existingMeta,
+                schemas,
+            };
+        }
+        catch {
+            // Match attachSessionState shape — fail-open. The hint is a
+            // discoverability aid, never load-bearing for the tool's own work.
+        }
+    }
+    /**
+     * ADR-208 Primitive B — bump the session-mutation counters and attach
+     * the resolved `_meta.session_state` to a successful write-tool result.
+     * Mutates `result` in-place to keep the existing return contract.
+     * Fail-open: any error here is swallowed — ambient state is best-effort
+     * and must not turn a successful mutation into a tool failure.
+     */
+    async attachSessionState(result, toolName) {
+        const cacheKey = this.getSessionCacheKey();
+        if (!cacheKey)
+            return;
+        try {
+            incrementSessionMutations(cacheKey);
+            const sessionState = await buildSessionState(cacheKey, this.fetchSessionCounts);
+            if (!sessionState)
+                return;
+            const existingMeta = result._meta ?? {};
+            result._meta = {
+                ...existingMeta,
+                session_state: sessionState,
+            };
+        }
+        catch {
+            // Swallow — ADR-208 explicitly mandates fail-open. The counter has
+            // already advanced; not attaching session_state on this turn just
+            // means the agent gets the bumped counters on the next mutation.
+            void toolName;
+        }
+    }
+    /**
+     * Execute a tool by name. `ctx.server` carries the transport-scoped
+     * MCP `Server` reference so executors that need `server.elicitInput()`
+     * (ADR-200 Phase 1) can reach it. Each per-request HTTP server is
+     * different; passing it through positionally avoids registry-level
+     * mutable state that would race between concurrent requests.
+     */
+    async executeTool(name, args, ctx) {
+        const startTime = Date.now();
+        const tool = this.tools.get(name);
+        if (!tool) {
+            throw new ToolExecutionError(`Tool not found: ${name}`);
+        }
+        const metadata = getToolMetadata(name);
+        // ── Session freshness gate (ADR-151) ──
+        if (metadata?.risk === "destructive" &&
+            this.config &&
+            !this.config.lobbyMode) {
+            const creds = readCredentials(this.config.credentialsPath);
+            if (creds?.authenticated_at) {
+                const authAge = Date.now() - new Date(creds.authenticated_at).getTime();
+                const sevenDays = 7 * 24 * 60 * 60 * 1000;
+                if (authAge > sevenDays) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: 'this action requires re-verification — say "sign me in" to confirm your identity',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
+        }
+        // ── Destructive confirmation gate ──
+        if (metadata?.risk === "destructive") {
+            const confirmationToken = args.confirmation_token;
+            if (!confirmationToken) {
+                // First call — generate preview and return confirmation challenge
+                const token = generateConfirmationToken(name, args);
+                const preview = await this.buildDestructivePreview(name, args);
+                const response = {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                status: "confirmation_required",
+                                confirmation_token: token,
+                                expires_in: 120,
+                                preview,
+                            }, null, 2),
+                        },
+                    ],
+                    structuredContent: {
+                        status: "confirmation_required",
+                        confirmation_token: token,
+                        expires_in: 120,
+                        preview,
+                    },
+                };
+                // Fire-and-forget audit for confirmation challenge
+                this.auditLogger
+                    ?.logToolExecution({
+                    tool_name: name,
+                    tool_category: metadata?.category || "unknown",
+                    risk_level: "destructive",
+                    parameters: this.sanitizeParams(args),
+                    result_status: "confirmation_required",
+                    confirmation_token: token,
+                    execution_time_ms: Date.now() - startTime,
+                    caller_identity: this.callerContext.callerIdentity,
+                    transport: this.callerContext.transport,
+                })
+                    .catch(() => { }); // Never block on audit
+                return response;
+            }
+            // Second call — validate token
+            const validation = validateAndConsumeToken(confirmationToken, name, args);
+            if (!validation.valid) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: validation.reason?.includes("expired")
+                                    ? "CONFIRMATION_EXPIRED"
+                                    : "CONFIRMATION_INVALID",
+                                message: validation.reason,
+                                retry_safe: false,
+                                suggestion: "start the operation again without the confirmation token",
+                            }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Token valid — fall through to execute
+        }
+        // ── Normal execution ──
+        try {
+            const result = await tool.executor(args, ctx);
+            // Guard response size — truncate oversized payloads with recovery hint
+            if (result?.content) {
+                for (const block of result.content) {
+                    if (block.type === "text" && typeof block.text === "string") {
+                        block.text = guardResponseSize(block.text, name);
+                    }
+                }
+            }
+            // ADR-208 Primitive B — ambient session-state on write-tool results.
+            // Read tools (`risk: safe` ⇒ `readOnlyHint: true`) skip this entirely so
+            // the high-volume read path stays cheap. `result.isError === true` also
+            // skips because a failed mutation didn't change catalog state.
+            const isWriteTool = (metadata?.risk ?? this.classifyTool(name)) !== "safe";
+            if (isWriteTool && result && !result.isError) {
+                await this.attachSessionState(result, name);
+            }
+            // P3c — schema-resource hint on every workflow-tagged tool result
+            // (Option X — applies to read companions too so the agent gets the
+            // pointer regardless of which verb they hit first). Runs after
+            // `attachSessionState` so the two `_meta` keys co-exist via merge.
+            // Skipped on errors (workflow didn't progress) and on infrastructure
+            // tools (handled inside `attachSchemaHints`).
+            if (result && !result.isError) {
+                this.attachSchemaHints(result, tool.definition.workflows);
+            }
+            // ADR-208 acceptance criterion 5 — briefing run resets the
+            // since_last_briefing counter. Handled in the wrapper so the briefing
+            // tool itself stays oblivious to the cacheKey it doesn't own.
+            if (name === "pica_dashboard_briefing" && result && !result.isError) {
+                const cacheKey = this.getSessionCacheKey();
+                if (cacheKey)
+                    resetSinceLastBriefing(cacheKey);
+            }
+            // Fire-and-forget audit
+            this.auditLogger
+                ?.logToolExecution({
+                tool_name: name,
+                tool_category: metadata?.category || "unknown",
+                risk_level: metadata?.risk || this.classifyTool(name),
+                parameters: this.sanitizeParams(args),
+                result_status: "success",
+                execution_time_ms: Date.now() - startTime,
+                caller_identity: this.callerContext.callerIdentity,
+                transport: this.callerContext.transport,
+            })
+                .catch(() => { }); // Never block on audit
+            return result;
+        }
+        catch (error) {
+            const formatted = formatError(error);
+            const parsed = JSON.parse(formatted.text);
+            // Attach recovery hint if available for this tool + error code
+            const hint = getRecoveryHint(name, parsed.error);
+            if (hint) {
+                parsed.suggestion = hint.suggestion;
+                if (hint.next_tool) {
+                    parsed.next_tool = hint.next_tool;
+                }
+            }
+            // Fire-and-forget audit for errors
+            this.auditLogger
+                ?.logToolExecution({
+                tool_name: name,
+                tool_category: metadata?.category || "unknown",
+                risk_level: metadata?.risk || this.classifyTool(name),
+                parameters: this.sanitizeParams(args),
+                result_status: "error",
+                error_code: parsed.error,
+                execution_time_ms: Date.now() - startTime,
+                caller_identity: this.callerContext.callerIdentity,
+                transport: this.callerContext.transport,
+            })
+                .catch(() => { }); // Never block on audit
+            return {
+                content: [{ type: "text", text: JSON.stringify(parsed, null, 2) }],
+                isError: true,
+            };
+        }
+    }
+}
+//# sourceMappingURL=index.js.map