@nordsym/apiclaw 2.0.0 → 2.2.0

package/dist/index.js

@@ -21,10 +21,11 @@ import { executeMetered } from './metered.js';
 import { logAPICall } from './mcp-analytics.js';
 import { isOpenAPI, executeOpenAPI, listOpenAPIs, getOpenAPIBaseUrl } from './open-apis.js';
 import { getGateway, isGatewayEnabled } from './gateway-client.js';
-import { PROXY_PROVIDERS } from './proxy.js';
 import { requiresConfirmationAsync, createPendingAction, consumePendingAction, generatePreview, validateParams } from './confirmation.js';
 import { executeCapability, listCapabilities, hasCapability } from './capability-router.js';
 import { readSession, writeSession, clearSession, getMachineFingerprint, detectMCPClient } from './session.js';
+import { requireVerifiedOwner } from './registration-guard.js';
+import { emitFunnelEvent, hasLocalMarker, setLocalMarker } from './funnel-client.js';
 import { ConvexHttpClient } from 'convex/browser';
 import { getOrCreateCustomer, createMeteredCheckoutSession, getUsageSummary, METERED_BILLING } from './stripe.js';
 import { estimateCost } from './metered.js';
@@ -36,6 +37,7 @@ const CONVEX_URL = process.env.CONVEX_URL || 'https://adventurous-avocet-799.con
 const convex = new ConvexHttpClient(CONVEX_URL);
 let workspaceContext = null;
 let currentAgentId = null; // Agent ID from agents table (set on startup)
+let pendingRegistrationEmail = null; // Email waiting for OTP verification
 const anonymousRateLimits = new Map();
 // Rate limit constants
 const ANONYMOUS_HOURLY_LIMIT = 5;
@@ -188,32 +190,21 @@ const rateLimitStore = new Map();
 // Unregistered (auto-provisioned, no email) users get this many calls before signup required
 const UNREGISTERED_CALL_LIMIT = 5;
 /**
- * For proxy providers, allow anonymous usage with rate limiting
+ * Check workspace access -- registration required for all API calls
  */
 function checkWorkspaceAccess(providerId) {
-    // Allow anonymous access for proxy providers
-    if (providerId && PROXY_PROVIDERS.includes(providerId)) {
-        if (!workspaceContext) {
-            // Anonymous user - check rate limits
-            const fingerprint = getMachineFingerprint();
-            const rateLimitCheck = checkAnonymousRateLimit(fingerprint);
-            if (!rateLimitCheck.allowed) {
-                return {
-                    allowed: false,
-                    error: rateLimitCheck.error,
-                    isAnonymous: true
-                };
-            }
-            return { allowed: true, isAnonymous: true };
-        }
-        // Authenticated user using proxy provider - allow with higher limits
-        return { allowed: true, isAnonymous: false };
-    }
-    // Non-proxy providers require authentication
+    // All API calls require registration now
     if (!workspaceContext) {
         return {
             allowed: false,
-            error: 'Not authenticated. Use register_owner to authenticate your workspace.'
+            error: JSON.stringify({
+                status: 'registration_required',
+                error: 'Registration required to call APIs.',
+                message: 'Ask the user for their email, then call register_owner({ email: "..." }). A 6-digit code will be sent. Then call verify_code with the code.',
+                action: 'register_owner',
+                free_tier: '50 API calls/month -- completely free.',
+            }, null, 2),
+            isAnonymous: true,
         };
     }
     if (workspaceContext.status !== 'active') {
@@ -256,6 +247,49 @@ function checkWorkspaceAccess(providerId) {
     }
     return { allowed: true, isAnonymous: false };
 }
+/**
+ * Single enforcement entry point for every paying call path.
+ * Returns either a verified workspace context or an MCP-formatted block response.
+ */
+function enforceOwner(channel) {
+    const result = requireVerifiedOwner(workspaceContext);
+    if (result.ok) {
+        return { ok: true, ctx: result.ctx };
+    }
+    // Diagnostic: record why the call was blocked.
+    try {
+        emitFunnelEvent({
+            event: 'call_api_blocked',
+            workspaceId: workspaceContext?.workspaceId,
+            email: workspaceContext?.email,
+            fingerprint: getMachineFingerprint(),
+            mcpClient: detectMCPClient(),
+            platform: process.platform,
+            version: process.env.npm_package_version || 'unknown',
+            props: { reason: result.reason, channel },
+        });
+        if (result.reason === 'quota_exceeded') {
+            emitFunnelEvent({
+                event: 'quota_hit',
+                workspaceId: workspaceContext?.workspaceId,
+                email: workspaceContext?.email,
+                fingerprint: getMachineFingerprint(),
+                version: process.env.npm_package_version || 'unknown',
+                props: { tier: workspaceContext?.tier, limit: workspaceContext?.usageCount },
+            });
+        }
+    }
+    catch { /* non-blocking */ }
+    return {
+        ok: false,
+        response: {
+            content: [{ type: 'text', text: JSON.stringify(result.payload, null, 2) }],
+            isError: true,
+        },
+    };
+}
+// Per-process marker: ensure first_call_api_success fires once per server boot.
+let firstCallEmitted = false;
 /**
  * Get customer API key from environment variable
  * Convention: {PROVIDER}_API_KEY (e.g., COACCEPT_API_KEY, ELKS_API_KEY)
@@ -408,7 +442,7 @@ const tools = [
     },
     {
         name: 'call_api',
-        description: `Execute an API call through APIClaw. Supports single calls AND multi-step chains.
+        description: `Execute an API call through APIClaw. Requires registration (free). If not registered, call register_owner first.
 
 SINGLE CALL: Provide provider + action + params
 CHAIN: Provide chain array to execute multiple APIs in sequence/parallel with cross-step references.
@@ -580,7 +614,7 @@ Example chain:
     // ============================================
     {
         name: 'register_owner',
-        description: 'Register your email to create a workspace. This authenticates your agent with APIClaw. You will receive a magic link to verify ownership.',
+        description: 'REQUIRED before using any API. Register your email to create a workspace. A 6-digit verification code will be sent to your email. After calling this, ask the user for the code and call verify_code.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -592,6 +626,24 @@ Example chain:
             required: ['email']
         }
     },
+    {
+        name: 'verify_code',
+        description: 'Verify the 6-digit code sent to your email after register_owner. This completes registration and activates your workspace. Ask the user to check their email and paste the code.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                email: {
+                    type: 'string',
+                    description: 'The email address used in register_owner'
+                },
+                code: {
+                    type: 'string',
+                    description: 'The 6-digit verification code from the email'
+                }
+            },
+            required: ['email', 'code']
+        }
+    },
     {
         name: 'check_workspace_status',
         description: 'Check your workspace status, tier, and usage remaining.',
@@ -721,37 +773,32 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         switch (name) {
             case 'apiclaw_help': {
+                const isAuthenticated = !!workspaceContext;
                 const helpText = `
-🦞 APIClaw — The API Layer for AI Agents
+🦞 APIClaw -- The API Layer for AI Agents
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-DISCOVER APIs:
+${!isAuthenticated ? `
+GET STARTED (free):
+  1. register_owner({ email: "you@example.com" })  — sends 6-digit code
+  2. verify_code({ email: "you@example.com", code: "123456" })  — activates workspace
+` : `
+STATUS: Authenticated as ${workspaceContext.email} (${workspaceContext.tier} tier)
+`}
+DISCOVER APIs (free, no registration needed):
   discover_apis({ query: "send SMS to Sweden" })
-  discover_apis({ query: "search the web", max_results: 10 })
   discover_apis({ query: "text to speech", category: "ai" })
 
-GET DETAILS:
-  get_api_details({ api_id: "46elks" })
-
-DIRECT CALL (8 APIs, no key needed):
-  get_connected_providers()
-  call_api({ provider: "brave_search", endpoint: "search", params: { query: "AI agents" } })
+CALL APIs (requires free registration):
+  call_api({ provider: "brave_search", action: "search", params: { q: "AI agents" } })
+  call_api({ provider: "elevenlabs", action: "tts", params: { text: "Hello" } })
 
-Available direct-call providers:
-  • brave_search — Web search
-  • 46elks — SMS (Sweden)
-  • twilio — SMS (Global)
-  • resend — Email
-  • openrouter — LLM routing (100+ models)
-  • elevenlabs — Text-to-speech
-  • replicate — AI models (images, video, audio)
-  • firecrawl — Web scraping & crawling
-  • github — Code repos & developer data
-  • e2b — Code sandbox for AI agents
+23 MANAGED PROVIDERS:
+  OpenAI, Anthropic, xAI/Grok, Groq, Mistral, OpenRouter, Together AI,
+  Replicate, ElevenLabs, Deepgram, AssemblyAI, Brave Search, Firecrawl,
+  Serper, Resend, 46elks, Twilio, E2B, Stability AI, Cohere, Voyage AI,
+  GitHub, APILayer (27 sub-APIs)
 
-BROWSE:
-  list_categories()
-  list_all_apis({ category: "communication", limit: 20 })
+26,700+ DISCOVERABLE | 1,654 CALLABLE | Free tier: 50 calls/month
 
 Docs: https://apiclaw.cloud
 `;
@@ -1043,6 +1090,12 @@ Docs: https://apiclaw.cloud
                 };
             }
             case 'call_api': {
+                // ============================================
+                // REGISTRATION GATE: requireVerifiedOwner (single source of truth)
+                // ============================================
+                const gate = enforceOwner("mcp:call_api");
+                if (!gate.ok)
+                    return gate.response;
                 const provider = args?.provider;
                 const action = args?.action;
                 const params = args?.params || {};
@@ -1070,32 +1123,7 @@ Docs: https://apiclaw.cloud
                 // CHAIN EXECUTION MODE
                 // ============================================
                 if (chain && Array.isArray(chain) && chain.length > 0) {
-                    // Check workspace access for chains
-                    const access = checkWorkspaceAccess();
-                    if (!access.allowed) {
-                        // If error is already formatted JSON (from rate limit checks), return as-is
-                        if (access.error?.startsWith('{')) {
-                            return {
-                                content: [{
-                                        type: 'text',
-                                        text: access.error
-                                    }],
-                                isError: true
-                            };
-                        }
-                        // Otherwise, wrap in standard error format
-                        return {
-                            content: [{
-                                    type: 'text',
-                                    text: JSON.stringify({
-                                        status: 'error',
-                                        error: access.error,
-                                        hint: 'Use register_owner to authenticate your workspace.',
-                                    }, null, 2)
-                                }],
-                            isError: true
-                        };
-                    }
+                    // Gate already enforced at top of call_api via enforceOwner().
                     try {
                         // Construct ChainDefinition from the input
                         const chainDefinition = {
@@ -1423,6 +1451,37 @@ Docs: https://apiclaw.cloud
                 if (isGatewayEnabled() && result.success && workspaceContext && !isFreeAPI) {
                     workspaceContext.usageCount = (workspaceContext.usageCount || 0) + 1;
                 }
+                // Funnel: call_api_error (provider-level failure)
+                if (!result.success && workspaceContext) {
+                    emitFunnelEvent({
+                        event: 'call_api_error',
+                        workspaceId: workspaceContext.workspaceId,
+                        email: workspaceContext.email,
+                        fingerprint: getMachineFingerprint(),
+                        version: process.env.npm_package_version || 'unknown',
+                        props: {
+                            provider: result.provider || provider,
+                            action: result.action || action,
+                            errorCode: (result.error || '').slice(0, 80) || 'unknown',
+                        },
+                    });
+                }
+                // Funnel: first_call_api_success (once per workspace, deduped server-side)
+                if (result.success && workspaceContext && !isFreeAPI && !firstCallEmitted) {
+                    firstCallEmitted = true;
+                    emitFunnelEvent({
+                        event: 'first_call_api_success',
+                        email: workspaceContext.email,
+                        workspaceId: workspaceContext.workspaceId,
+                        sessionToken: workspaceContext.sessionToken,
+                        fingerprint: getMachineFingerprint(),
+                        mcpClient: detectMCPClient(),
+                        platform: process.platform,
+                        version: process.env.npm_package_version || 'unknown',
+                        dedupeKey: `first_call:${workspaceContext.workspaceId}`,
+                        props: { provider, action, channel: 'mcp:call_api' },
+                    });
+                }
                 // Build response with signup nudge for unregistered users
                 const responseData = {
                     status: result.success ? 'success' : 'error',
@@ -1474,6 +1533,10 @@ Docs: https://apiclaw.cloud
                 };
             }
             case 'capability': {
+                // Registration gate: requireVerifiedOwner (single source of truth)
+                const capGate = enforceOwner("mcp:capability");
+                if (!capGate.ok)
+                    return capGate.response;
                 const capabilityId = args?.capability;
                 const action = args?.action;
                 const params = args?.params || {};
@@ -1553,6 +1616,14 @@ Docs: https://apiclaw.cloud
             case 'register_owner': {
                 const email = args?.email;
                 if (!email || !email.includes('@')) {
+                    emitFunnelEvent({
+                        event: 'register_owner_failed',
+                        email,
+                        fingerprint: getMachineFingerprint(),
+                        mcpClient: detectMCPClient(),
+                        version: process.env.npm_package_version || 'unknown',
+                        props: { reason: 'invalid_email' },
+                    });
                     return {
                         content: [{
                                 type: 'text',
@@ -1565,10 +1636,9 @@ Docs: https://apiclaw.cloud
                     };
                 }
                 try {
-                    // Check if workspace already exists
+                    // Check if workspace already exists and is active -- auto-login
                     const existing = await convex.query("workspaces:getByEmail", { email });
                     if (existing && existing.status === 'active') {
-                        // Workspace exists and is active - create session directly
                         const fingerprint = getMachineFingerprint();
                         const sessionResult = await convex.mutation("workspaces:createAgentSession", {
                             workspaceId: existing.id,
@@ -1576,21 +1646,16 @@ Docs: https://apiclaw.cloud
                         });
                         if (sessionResult.success) {
                             writeSession(sessionResult.sessionToken, existing.id, email);
-                            // Claim anonymous usage history
                             try {
                                 const claimResult = await convex.mutation("workspaces:claimAnonymousUsage", {
                                     workspaceId: existing.id,
                                     machineFingerprint: fingerprint,
                                 });
                                 if (claimResult.success && claimResult.claimedCount) {
-                                    console.error(`[APIClaw] ✓ Claimed ${claimResult.claimedCount} anonymous usage records`);
+                                    console.error(`[APIClaw] Claimed ${claimResult.claimedCount} anonymous usage records`);
                                 }
                             }
-                            catch (err) {
-                                // Non-critical error, just log it
-                                console.error('[APIClaw] Warning: Failed to claim anonymous usage:', err);
-                            }
-                            // Update global context
+                            catch (_) { }
                             workspaceContext = {
                                 sessionToken: sessionResult.sessionToken,
                                 workspaceId: existing.id,
@@ -1617,26 +1682,13 @@ Docs: https://apiclaw.cloud
                             };
                         }
                     }
-                    // Create workspace and magic link
-                    const createResult = await convex.mutation("workspaces:createWorkspace", { email });
-                    let workspaceId;
-                    if (createResult.success) {
-                        workspaceId = createResult.workspaceId;
-                    }
-                    else if (createResult.error === 'workspace_exists') {
-                        workspaceId = createResult.workspaceId;
-                    }
-                    else {
-                        throw new Error(createResult.error);
-                    }
-                    // Create magic link
+                    // New user or pending workspace -- send OTP
                     const fingerprint = getMachineFingerprint();
-                    const magicLinkResult = await convex.mutation("workspaces:createMagicLink", {
+                    const otpResult = await convex.mutation("workspaces:createOTP", {
                         email,
                         fingerprint,
                     });
-                    // Send magic link via email
-                    const verifyUrl = `https://apiclaw.cloud/auth/verify?token=${magicLinkResult.token}`;
+                    // Send OTP email
                     const emailResponse = await fetch('https://api.resend.com/emails', {
                         method: 'POST',
                         headers: {
@@ -1646,23 +1698,56 @@ Docs: https://apiclaw.cloud
                         body: JSON.stringify({
                             from: 'APIClaw <noreply@apiclaw.cloud>',
                             to: email,
-                            subject: 'Verify your APIClaw workspace',
-                            html: `<p>Click to verify: <a href="${verifyUrl}">${verifyUrl}</a></p><p>Expires in 15 minutes.</p>`
+                            subject: `Your APIClaw verification code: ${otpResult.code}`,
+                            html: `
+                <div style="font-family: Inter, sans-serif; max-width: 480px; margin: 0 auto; padding: 40px 24px;">
+                  <div style="text-align: center; margin-bottom: 32px;">
+                    <span style="font-size: 48px;">🦞</span>
+                  </div>
+                  <h1 style="font-size: 24px; font-weight: 700; color: #0A0A0A; text-align: center; margin-bottom: 8px;">Your verification code</h1>
+                  <p style="font-size: 16px; color: #525252; text-align: center; margin-bottom: 32px;">Paste this code in your terminal to activate APIClaw.</p>
+                  <div style="background: #F5F5F5; border: 1px solid #E5E5E5; border-radius: 12px; padding: 24px; text-align: center; margin-bottom: 24px;">
+                    <code style="font-size: 36px; font-weight: 700; letter-spacing: 0.3em; color: #EF4444; font-family: 'JetBrains Mono', monospace;">${otpResult.code}</code>
+                  </div>
+                  <p style="font-size: 13px; color: #737373; text-align: center;">This code expires in 10 minutes. If you didn't request this, ignore this email.</p>
+                  <hr style="border: none; border-top: 1px solid #E5E5E5; margin: 32px 0 16px;" />
+                  <p style="font-size: 12px; color: #A3A3A3; text-align: center;">APIClaw -- The API Layer For AI Agents</p>
+                </div>
+              `
                         })
                     });
                     if (!emailResponse.ok) {
                         const errorData = await emailResponse.text();
+                        emitFunnelEvent({
+                            event: 'register_owner_failed',
+                            email,
+                            fingerprint: getMachineFingerprint(),
+                            mcpClient: detectMCPClient(),
+                            version: process.env.npm_package_version || 'unknown',
+                            props: { reason: 'email_send_failed' },
+                        });
                         throw new Error(`Failed to send verification email: ${errorData}`);
                     }
+                    // Store pending email for verify_code
+                    pendingRegistrationEmail = email;
+                    // Funnel: register_owner
+                    emitFunnelEvent({
+                        event: 'register_owner',
+                        email,
+                        fingerprint: getMachineFingerprint(),
+                        mcpClient: detectMCPClient(),
+                        platform: process.platform,
+                        version: process.env.npm_package_version || 'unknown',
+                    });
                     return {
                         content: [{
                                 type: 'text',
                                 text: JSON.stringify({
-                                    status: 'pending_verification',
-                                    message: 'Workspace created! Check your email for verification link.',
+                                    status: 'code_sent',
+                                    message: `Verification code sent to ${email}`,
+                                    next_step: 'Ask the user to check their email for a 6-digit code, then call verify_code with the email and code.',
                                     email,
-                                    expires_in_minutes: 15,
-                                    next_step: 'Check your email, click the verification link, then run check_workspace_status',
+                                    expires_in_minutes: 10,
                                 }, null, 2)
                             }]
                     };
@@ -1680,6 +1765,129 @@ Docs: https://apiclaw.cloud
                     };
                 }
             }
+            case 'verify_code': {
+                const email = args?.email || pendingRegistrationEmail;
+                const code = args?.code;
+                if (!email || !code) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    status: 'error',
+                                    error: 'Both email and code are required.',
+                                    hint: 'Call register_owner first to receive a verification code.',
+                                }, null, 2)
+                            }],
+                        isError: true
+                    };
+                }
+                try {
+                    const fingerprint = getMachineFingerprint();
+                    const result = await convex.mutation("workspaces:verifyOTP", {
+                        email,
+                        code: code.trim(),
+                        fingerprint,
+                    });
+                    if (!result.success) {
+                        // Increment attempt counter
+                        try {
+                            await convex.mutation("workspaces:incrementOTPAttempt", { email, code: code.trim() });
+                        }
+                        catch (_) { }
+                        const reason = result.error === 'code_expired' ? 'expired'
+                            : result.error === 'attempts_exceeded' ? 'attempts_exceeded'
+                                : 'invalid';
+                        emitFunnelEvent({
+                            event: 'verify_code_failed',
+                            email,
+                            fingerprint: getMachineFingerprint(),
+                            mcpClient: detectMCPClient(),
+                            version: process.env.npm_package_version || 'unknown',
+                            props: { reason },
+                        });
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        status: 'error',
+                                        error: result.message || 'Verification failed',
+                                        hint: result.error === 'code_expired'
+                                            ? 'Run register_owner again to get a new code.'
+                                            : 'Check the code and try again.',
+                                    }, null, 2)
+                                }],
+                            isError: true
+                        };
+                    }
+                    // Success! Save session
+                    writeSession(result.sessionToken, result.workspace.id, result.workspace.email);
+                    // Claim anonymous usage
+                    try {
+                        const claimResult = await convex.mutation("workspaces:claimAnonymousUsage", {
+                            workspaceId: result.workspace.id,
+                            machineFingerprint: fingerprint,
+                        });
+                        if (claimResult.success && claimResult.claimedCount) {
+                            console.error(`[APIClaw] Claimed ${claimResult.claimedCount} anonymous usage records`);
+                        }
+                    }
+                    catch (_) { }
+                    // Update global context
+                    workspaceContext = {
+                        sessionToken: result.sessionToken,
+                        workspaceId: result.workspace.id,
+                        email: result.workspace.email,
+                        tier: result.workspace.tier,
+                        usageRemaining: result.workspace.usageLimit - result.workspace.usageCount,
+                        usageCount: result.workspace.usageCount,
+                        status: result.workspace.status,
+                    };
+                    pendingRegistrationEmail = null;
+                    // Funnel: verify_code (dedupe per workspace so re-verifies don't double-count)
+                    emitFunnelEvent({
+                        event: 'verify_code',
+                        email: result.workspace.email,
+                        workspaceId: result.workspace.id,
+                        fingerprint: getMachineFingerprint(),
+                        sessionToken: result.sessionToken,
+                        mcpClient: detectMCPClient(),
+                        platform: process.platform,
+                        version: process.env.npm_package_version || 'unknown',
+                        dedupeKey: `verify_code:${result.workspace.id}`,
+                        props: { isNewUser: !!result.isNewUser },
+                    });
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    status: 'success',
+                                    message: result.isNewUser
+                                        ? `Welcome to APIClaw! Workspace activated for ${result.workspace.email}`
+                                        : `Welcome back! Authenticated as ${result.workspace.email}`,
+                                    workspace: {
+                                        email: result.workspace.email,
+                                        tier: result.workspace.tier,
+                                        usageCount: result.workspace.usageCount,
+                                        usageLimit: result.workspace.usageLimit,
+                                    },
+                                    ready: 'You can now use discover_apis and call_api.',
+                                }, null, 2)
+                            }]
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    status: 'error',
+                                    error: error instanceof Error ? error.message : 'Verification failed',
+                                }, null, 2)
+                            }],
+                        isError: true
+                    };
+                }
+            }
             case 'check_workspace_status': {
                 // Check if we have a local session
                 const session = readSession();
@@ -2016,21 +2224,10 @@ Docs: https://apiclaw.cloud
                         isError: true
                     };
                 }
-                // Check workspace access
-                const access = checkWorkspaceAccess();
-                if (!access.allowed) {
-                    return {
-                        content: [{
-                                type: 'text',
-                                text: JSON.stringify({
-                                    status: 'error',
-                                    error: access.error,
-                                    hint: 'Use register_owner to authenticate your workspace.',
-                                }, null, 2)
-                            }],
-                        isError: true
-                    };
-                }
+                // Registration gate: requireVerifiedOwner (single source of truth)
+                const resumeGate = enforceOwner("mcp:resume_chain");
+                if (!resumeGate.ok)
+                    return resumeGate.response;
                 try {
                     // Note: The resume_chain function requires the original chain definition
                     // In practice, you'd store this or require the caller to provide it
@@ -2141,6 +2338,27 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     trackStartup();
+    // Funnel: first_run (once per fingerprint, persisted across restarts)
+    try {
+        const fp = getMachineFingerprint();
+        const mcpClient = detectMCPClient();
+        const version = process.env.npm_package_version || 'unknown';
+        const dedupeKey = `first_run:${fp}`;
+        if (!hasLocalMarker(dedupeKey)) {
+            emitFunnelEvent({
+                event: 'first_run',
+                fingerprint: fp,
+                mcpClient,
+                platform: process.platform,
+                version,
+                dedupeKey,
+            });
+            setLocalMarker(dedupeKey);
+        }
+    }
+    catch {
+        /* non-blocking */
+    }
     // Validate session on startup
     const hasValidSession = await validateSession();
     // Register/update agent identity (fire-and-forget)