@nexalink/carecompass-sdk 0.2.0-beta.15 → 0.4.0-beta.15

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createDefaultCareCompassConfig, validateCareCompassConfig, } from "./schema.js";
+import { careCompassApiBaseUrlSchema, createDefaultCareCompassConfig, validateCareCompassConfig, } from "./schema.js";
 import { normalizeApiKey, resolveApiKey, resolveCredentialsPath, writeStoredApiKey, } from "./credentials.js";
 import { generateCareCompassIframeSnippet, generateCareCompassSnippet, } from "./snippet.js";
 import { CARECOMPASS_TELEMETRY_ERROR_CODES, CARECOMPASS_TELEMETRY_EVENTS, createCareCompassCliTelemetry, } from "./telemetry.js";
@@ -31,6 +31,277 @@ support resources, and appropriate next steps. Stay out of diagnosis, treatment
 planning, emergency triage, legal advice, and coverage guarantees. When a member
 needs clinical, emergency, plan-specific, or account-specific help that requires
 a human, route them to the customer's approved support resources.`;
+const CLI_COMMAND_ALLOWLIST = new Set([
+    "auth",
+    "completion",
+    "config",
+    "configure",
+    "doctor",
+    "embed",
+    "health",
+    "help",
+    "init",
+    "login",
+    "logout",
+    "query",
+    "setup",
+    "snippet",
+    "validate",
+    "version",
+]);
+const UNAUTHENTICATED_AUTH_ATTEMPT_LIMIT = 2;
+const UNAUTHENTICATED_AUTH_RATE_LIMIT_WINDOW_MS = 15 * 60 * 1000;
+const UNAUTHENTICATED_AUTH_RATE_LIMIT_FILE = "auth-rate-limit.json";
+class CliTelemetryError extends Error {
+    constructor(message, telemetry) {
+        super(message);
+        this.telemetry = telemetry;
+    }
+}
+const sanitizeCommandName = (command) => {
+    const normalized = command === "--help" || command === "-h" ? "help" : command;
+    if (command === "--version" || command === "-v")
+        return "version";
+    return CLI_COMMAND_ALLOWLIST.has(normalized) ? normalized : "unknown_command";
+};
+const authTelemetryForSource = (source) => {
+    if (source === "environment") {
+        return { authMethod: "env_var", keySource: "env_var" };
+    }
+    if (source === "file") {
+        return { authMethod: "config_file", keySource: "config_file" };
+    }
+    return { authMethod: "api_key", keySource: "cli_flag" };
+};
+const unauthenticatedRateLimitPath = (io) => io.env.CARECOMPASS_AUTH_RATE_LIMIT_PATH ??
+    join(dirname(resolveCredentialsPath(io.env)), UNAUTHENTICATED_AUTH_RATE_LIMIT_FILE);
+const unauthenticatedRateLimitKey = (io) => {
+    const keyMaterial = io.env.CARECOMPASS_AUTH_RATE_LIMIT_KEY
+        ? `explicit:${io.env.CARECOMPASS_AUTH_RATE_LIMIT_KEY}`
+        : io.env.CARECOMPASS_CLIENT_IP
+            ? `ip:${io.env.CARECOMPASS_CLIENT_IP}`
+            : `credentials:${resolveCredentialsPath(io.env)}`;
+    return createHash("sha256")
+        .update("carecompass unauthenticated auth rate limit")
+        .update(keyMaterial)
+        .digest("hex");
+};
+const emptyUnauthenticatedAuthLedger = () => ({
+    version: 1,
+    entries: {},
+});
+const readUnauthenticatedAuthLedger = (path) => {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed.version !== 1 || typeof parsed.entries !== "object") {
+            return emptyUnauthenticatedAuthLedger();
+        }
+        const entries = {};
+        for (const [key, value] of Object.entries(parsed.entries)) {
+            if (typeof value === "object" &&
+                value !== null &&
+                typeof value.failures ===
+                    "number" &&
+                typeof value.firstAttemptAt ===
+                    "number" &&
+                typeof value.lastAttemptAt ===
+                    "number") {
+                entries[key] = value;
+            }
+        }
+        return { version: 1, entries };
+    }
+    catch {
+        return emptyUnauthenticatedAuthLedger();
+    }
+};
+const writeUnauthenticatedAuthLedger = (path, ledger) => {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(ledger, null, 2)}\n`, { mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // Some filesystems do not support chmod; the ledger contains only hashed
+        // limiter keys and counters.
+    }
+};
+const pruneUnauthenticatedAuthLedger = (ledger, now) => {
+    for (const [key, entry] of Object.entries(ledger.entries)) {
+        if (now - entry.firstAttemptAt >
+            UNAUTHENTICATED_AUTH_RATE_LIMIT_WINDOW_MS) {
+            delete ledger.entries[key];
+        }
+    }
+};
+const recordUnauthenticatedAuthFailure = (io) => {
+    const path = unauthenticatedRateLimitPath(io);
+    const key = unauthenticatedRateLimitKey(io);
+    const now = Date.now();
+    const ledger = readUnauthenticatedAuthLedger(path);
+    pruneUnauthenticatedAuthLedger(ledger, now);
+    const existing = ledger.entries[key];
+    const entry = existing &&
+        now - existing.firstAttemptAt <= UNAUTHENTICATED_AUTH_RATE_LIMIT_WINDOW_MS
+        ? existing
+        : { failures: 0, firstAttemptAt: now, lastAttemptAt: now };
+    entry.failures += 1;
+    entry.lastAttemptAt = now;
+    ledger.entries[key] = entry;
+    writeUnauthenticatedAuthLedger(path, ledger);
+    const failures = entry.failures;
+    if (failures < UNAUTHENTICATED_AUTH_ATTEMPT_LIMIT)
+        return null;
+    return new CliTelemetryError("Too many failed authentication attempts. Wait before trying again or verify the API key in the Nexalink console.", {
+        errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.RATE_LIMIT_EXCEEDED,
+        failureCategory: "rate_limit_error",
+    });
+};
+const resetUnauthenticatedAuthFailures = (io) => {
+    const path = unauthenticatedRateLimitPath(io);
+    const ledger = readUnauthenticatedAuthLedger(path);
+    delete ledger.entries[unauthenticatedRateLimitKey(io)];
+    writeUnauthenticatedAuthLedger(path, ledger);
+};
+const normalizeBaaStatus = (value) => {
+    if (value === "signed" || value === "pending" || value === "not_required") {
+        return value;
+    }
+    return "signed";
+};
+const classifyAuthFailure = (status, message) => {
+    const normalized = message.toLowerCase();
+    if (status === 429 || normalized.includes("rate limit")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.RATE_LIMIT_EXCEEDED,
+            failureCategory: "rate_limit_error",
+            baaStatus: "signed",
+        };
+    }
+    if (status === 403 ||
+        normalized.includes("baa") ||
+        normalized.includes("business associate")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.BAA_REQUIRED,
+            failureCategory: "baa_not_signed",
+            baaStatus: "pending",
+        };
+    }
+    if (normalized.includes("expired")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.AUTH_KEY_EXPIRED,
+            failureCategory: "auth_error",
+            baaStatus: "signed",
+        };
+    }
+    return {
+        errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.AUTH_KEY_INVALID,
+        failureCategory: "auth_error",
+        baaStatus: "signed",
+    };
+};
+const classifyCliFailure = (error) => {
+    if (error instanceof CliTelemetryError)
+        return error.telemetry;
+    const code = error && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : "";
+    const message = error instanceof Error ? error.message : String(error);
+    const normalized = message.toLowerCase();
+    if (code === "EACCES" || code === "EPERM") {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.PERMISSION_DENIED,
+            failureCategory: "permission_error",
+        };
+    }
+    if (code === "ENOENT" || normalized.includes("was not found")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CONFIG_NOT_FOUND,
+            failureCategory: "config_error",
+        };
+    }
+    if (normalized.includes("invalid carecompass config") ||
+        normalized.includes("unexpected argument") ||
+        normalized.includes("must be either") ||
+        normalized.includes("api base url")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CONFIG_INVALID,
+            failureCategory: "config_error",
+        };
+    }
+    if (normalized.includes("already exists")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CONFIG_ALREADY_EXISTS,
+            failureCategory: "config_error",
+        };
+    }
+    if (normalized.includes("missing nexalink api key")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.AUTH_KEY_MISSING,
+            failureCategory: "auth_error",
+        };
+    }
+    if (normalized.includes("api key format") ||
+        normalized.includes("invalid api key")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.AUTH_KEY_INVALID,
+            failureCategory: "auth_error",
+        };
+    }
+    if (normalized.includes("baa execution") ||
+        normalized.includes("business associate")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.BAA_REQUIRED,
+            failureCategory: "baa_not_signed",
+        };
+    }
+    if (normalized.includes("rate limit") || normalized.includes("quota")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.RATE_LIMIT_EXCEEDED,
+            failureCategory: "rate_limit_error",
+        };
+    }
+    if (normalized.includes("timed out") || normalized.includes("timeout")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.NET_TIMEOUT,
+            failureCategory: "network_error",
+        };
+    }
+    if (normalized.includes("could not reach")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.NET_UNREACHABLE,
+            failureCategory: "network_error",
+        };
+    }
+    if (normalized.includes("model load")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.MODEL_LOAD_FAILED,
+            failureCategory: "model_error",
+        };
+    }
+    if (normalized.includes("model") || normalized.includes("inference")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.MODEL_INFERENCE_FAILED,
+            failureCategory: "model_error",
+        };
+    }
+    if (normalized.includes("unknown command")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CLI_COMMAND_UNKNOWN,
+            failureCategory: "unknown",
+        };
+    }
+    if (normalized.includes("cancelled")) {
+        return {
+            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CLI_COMMAND_CANCELLED,
+            failureCategory: "unknown",
+        };
+    }
+    return {
+        errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.UNKNOWN_ERROR,
+        failureCategory: "unknown",
+    };
+};
 function parseArgs(argv) {
     const [command = "help", ...rest] = argv;
     const flags = {};
@@ -210,6 +481,12 @@ const signupUrls = (flags, io) => ({
         io.env.CARECOMPASS_DEVELOPER_SIGNUP_URL ??
         DEFAULT_DEVELOPER_SIGNUP_URL,
 });
+function resolveTrustedApiBaseUrl(value) {
+    const result = careCompassApiBaseUrlSchema.safeParse(value);
+    if (result.success)
+        return result.data;
+    throw new Error(result.error.issues.map((issue) => issue.message).join("\n"));
+}
 function rejectLegacyBaaInitFlags(flags, io) {
     const legacyFlag = LEGACY_BAA_INIT_FLAGS.find((flag) => flag in flags);
     if (!legacyFlag)
@@ -267,7 +544,7 @@ async function validateInitApiKey(apiBaseUrl, apiKey, accountType) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Network request failed";
-        throw new Error(`Could not reach CareCompass authentication API at ${url}. ${message}`);
+        throw new CliTelemetryError(`Could not reach CareCompass authentication API at ${url}. ${message}`, classifyCliFailure(new Error(`Could not reach CareCompass authentication API. ${message}`)));
     }
     const text = await response.text();
     let payload = {};
@@ -278,27 +555,33 @@ async function validateInitApiKey(apiBaseUrl, apiKey, accountType) {
         payload = {};
     }
     if (!response.ok || payload.ok === false) {
+        const message = payload.error ?? "Invalid API key.";
+        const failure = classifyAuthFailure(response.status, message);
         return {
             ok: false,
-            message: payload.error ?? "Invalid API key.",
+            message,
+            ...failure,
         };
     }
     const validatedType = typeof payload.accountType === "string"
         ? normalizeAccountType(payload.accountType)
         : null;
     if (!validatedType) {
+        const message = "Credential validation succeeded but did not return a recognized account type. Contact support@nexalink.care.";
         return {
             ok: false,
-            message: "Credential validation succeeded but did not return a recognized account type. Contact support@nexalink.care.",
+            message,
+            ...classifyAuthFailure(401, message),
         };
     }
     return {
         ok: true,
         accountType: validatedType,
+        baaStatus: normalizeBaaStatus(payload.baaStatus),
         setup: normalizeAuthSetup(payload.setup),
     };
 }
-async function resolveInitApiKey(flags, io, apiBaseUrl) {
+async function resolveInitApiKey(flags, io, apiBaseUrl, onAuthChecked = async () => undefined) {
     const credentialsPath = resolveCredentialsPath(io.env);
     let credentials = resolveApiKey(flagString(flags, "api-key"), io.env, credentialsPath);
     const urls = signupUrls(flags, io);
@@ -316,6 +599,7 @@ async function resolveInitApiKey(flags, io, apiBaseUrl) {
         const apiKey = useResolvedCredential
             ? credentials.apiKey
             : await promptForSecret(io, "Enter API key: ");
+        const authTelemetry = authTelemetryForSource(credentials.source);
         useResolvedCredential = false;
         credentials = { apiKey: null, source: "missing" };
         const normalizedApiKey = normalizeApiKey(apiKey);
@@ -324,9 +608,32 @@ async function resolveInitApiKey(flags, io, apiBaseUrl) {
             continue;
         }
         io.stdout.write("Validating credentials...\n");
-        const validation = await validateInitApiKey(apiBaseUrl, normalizedApiKey, accountType);
+        let validation;
+        try {
+            validation = await validateInitApiKey(apiBaseUrl, normalizedApiKey, accountType);
+        }
+        catch (error) {
+            const failure = classifyCliFailure(error);
+            await onAuthChecked({
+                authResult: "failure",
+                baaStatus: "signed",
+                keySource: authTelemetry.keySource,
+                ...failure,
+            });
+            throw error;
+        }
         if (!validation.ok) {
+            await onAuthChecked({
+                authResult: "failure",
+                baaStatus: validation.baaStatus,
+                keySource: authTelemetry.keySource,
+                errorCode: validation.errorCode,
+                failureCategory: validation.failureCategory,
+            });
             io.stdout.write(`${validation.message}\n`);
+            const rateLimitError = recordUnauthenticatedAuthFailure(io);
+            if (rateLimitError)
+                throw rateLimitError;
             continue;
         }
         if (validation.accountType !== accountType) {
@@ -338,9 +645,16 @@ async function resolveInitApiKey(flags, io, apiBaseUrl) {
             continue;
         }
         writeStoredApiKey(normalizedApiKey, credentialsPath);
+        resetUnauthenticatedAuthFailures(io);
         io.stdout.write(`Stored CareCompass credentials at ${credentialsPath}\n`);
         io.stdout.write("Sign-in successful.\n");
-        return { apiKey: normalizedApiKey, setup: validation.setup };
+        return {
+            apiKey: normalizedApiKey,
+            authMethod: authTelemetry.authMethod,
+            baaStatus: validation.baaStatus,
+            keySource: authTelemetry.keySource,
+            setup: validation.setup,
+        };
     }
 }
 function resolvePromptFile(config, configPath) {
@@ -349,8 +663,23 @@ function resolvePromptFile(config, configPath) {
         return config;
     // Prompt files are resolved relative to the config file so generated kits work
     // after the caller changes directories.
-    const resolvedPath = resolve(dirname(configPath), promptFile);
-    const systemInstruction = readFileSync(resolvedPath, "utf8").trim();
+    if (isAbsolute(promptFile)) {
+        throw new Error("Prompt file must stay inside the config directory.");
+    }
+    const configDir = realpathSync(resolve(dirname(configPath)));
+    const resolvedPath = resolve(configDir, promptFile);
+    let realPromptPath;
+    try {
+        realPromptPath = realpathSync(resolvedPath);
+    }
+    catch {
+        throw new Error(`CareCompass prompt file was not found: ${promptFile}`);
+    }
+    const relativePromptPath = relative(configDir, realPromptPath);
+    if (relativePromptPath.startsWith("..") || isAbsolute(relativePromptPath)) {
+        throw new Error("Prompt file must stay inside the config directory.");
+    }
+    const systemInstruction = readFileSync(realPromptPath, "utf8").trim();
     const validation = validateCareCompassConfig({
         ...config,
         prompt: {
@@ -562,16 +891,104 @@ export async function runCareCompassCli(argv = process.argv.slice(2), io = {
     // Start with anonymous CLI telemetry, then rebuild it with payer context after
     // a config has been generated or read.
     let cliTelemetry = createCareCompassCliTelemetry(cliSessionId);
-    let activeCommand = "unknown";
+    const sessionStartedAt = Date.now();
+    const rawCommand = argv[0] ?? "help";
+    const telemetryCommandName = sanitizeCommandName(rawCommand);
+    let commandStartedAt = sessionStartedAt;
+    let commandStartedCaptured = false;
+    let commandsAttempted = 0;
+    let commandsSucceeded = 0;
+    let commandsFailed = 0;
+    let activeCommand = rawCommand;
+    let authCheckedCaptured = false;
+    let initStartedCaptured = false;
+    let sessionEndedCaptured = false;
+    const captureAuthChecked = async (telemetry) => {
+        if (authCheckedCaptured)
+            return;
+        authCheckedCaptured = true;
+        await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_AUTH_CHECKED, {
+            authResult: telemetry.authResult,
+            failureCategory: telemetry.authResult === "success"
+                ? null
+                : (telemetry.failureCategory ?? "unknown"),
+            ...(telemetry.errorCode ? { errorCode: telemetry.errorCode } : {}),
+            baaStatus: telemetry.baaStatus,
+            keySource: telemetry.keySource,
+        });
+    };
+    const captureCommandStarted = async () => {
+        if (commandStartedCaptured)
+            return;
+        commandStartedCaptured = true;
+        commandStartedAt = Date.now();
+        commandsAttempted += 1;
+        await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_COMMAND_STARTED, {
+            commandName: telemetryCommandName,
+            commandArgsCount: Math.max(argv.length - 1, 0),
+        });
+    };
+    const captureCommandCompleted = async () => {
+        await captureCommandStarted();
+        commandsSucceeded += 1;
+        await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_COMMAND_COMPLETED, {
+            commandName: telemetryCommandName,
+            commandDurationMs: Date.now() - commandStartedAt,
+            tokensUsed: null,
+            modelId: null,
+        });
+    };
+    const authenticateConfigCommand = async (flags) => {
+        let credentials;
+        try {
+            credentials = requireApiKey(flags, io);
+        }
+        catch (error) {
+            const failure = classifyCliFailure(error);
+            await captureAuthChecked({
+                authResult: "failure",
+                baaStatus: "signed",
+                keySource: "cli_flag",
+                errorCode: failure.errorCode,
+                failureCategory: failure.failureCategory,
+            });
+            const rateLimitError = recordUnauthenticatedAuthFailure(io);
+            throw rateLimitError ?? error;
+        }
+        const config = readConfig(flagString(flags, "config") ?? DEFAULT_CONFIG_PATH);
+        resetUnauthenticatedAuthFailures(io);
+        cliTelemetry = createCareCompassCliTelemetry(cliSessionId, config);
+        await captureAuthChecked({
+            authResult: "success",
+            baaStatus: "not_required",
+            keySource: authTelemetryForSource(credentials.source).keySource,
+            failureCategory: null,
+        });
+        return { config, credentials };
+    };
+    const captureSessionEnded = async (exitReason) => {
+        if (sessionEndedCaptured)
+            return;
+        sessionEndedCaptured = true;
+        await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_SESSION_ENDED, {
+            sessionDurationMs: Date.now() - sessionStartedAt,
+            commandsAttempted,
+            commandsSucceeded,
+            commandsFailed,
+            exitReason,
+        });
+    };
     await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_STARTED);
     try {
         const { command, flags, positionals } = parseArgs(argv);
         activeCommand = command;
         if (command === "help" || command === "--help" || command === "-h") {
             printHelp(io);
+            await captureCommandCompleted();
             return 0;
         }
         if (command === "login") {
+            await captureCommandStarted();
             await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_LOGIN_STARTED);
             const apiKey = flagString(flags, "api-key") ?? positionals[0];
             if (!apiKey) {
@@ -581,20 +998,33 @@ export async function runCareCompassCli(argv = process.argv.slice(2), io = {
                     errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.AUTHENTICATION_FAILED,
                     failureCategory: "authentication",
                 });
+                commandsFailed += 1;
                 return 1;
             }
             const credentialsPath = resolveCredentialsPath(io.env);
             writeStoredApiKey(apiKey, credentialsPath);
             io.stdout.write(`Stored CareCompass credentials at ${credentialsPath}\n`);
             await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_LOGIN_SUCCEEDED);
+            await captureCommandCompleted();
             return 0;
         }
         if (command === "init") {
-            await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_INIT_STARTED);
             rejectLegacyBaaInitFlags(flags, io);
             const outputDir = flagString(flags, "output-dir") ?? DEFAULT_OUTPUT_DIR;
-            const apiBaseUrl = flagString(flags, "api-base-url") ?? DEFAULT_API_BASE_URL;
-            const initAuth = await resolveInitApiKey(flags, io, apiBaseUrl);
+            const apiBaseUrl = resolveTrustedApiBaseUrl(flagString(flags, "api-base-url") ?? DEFAULT_API_BASE_URL);
+            const initAuth = await resolveInitApiKey(flags, io, apiBaseUrl, captureAuthChecked);
+            const config = buildInitConfig(flags, initAuth.setup);
+            cliTelemetry = createCareCompassCliTelemetry(cliSessionId, config);
+            await captureAuthChecked({
+                authResult: "success",
+                baaStatus: initAuth.baaStatus,
+                keySource: initAuth.keySource,
+                failureCategory: null,
+            });
+            await captureCommandStarted();
+            const initStartedAt = Date.now();
+            await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_INIT_STARTED);
+            initStartedCaptured = true;
             const output = flagString(flags, "output") ??
                 join(outputDir, "carecompass.config.json");
             const snippetOutput = flagString(flags, "snippet-output") ??
@@ -617,8 +1047,6 @@ export async function runCareCompassCli(argv = process.argv.slice(2), io = {
                 }
             }
             mkdirSync(outputDir, { recursive: true });
-            const config = buildInitConfig(flags, initAuth.setup);
-            cliTelemetry = createCareCompassCliTelemetry(cliSessionId, config);
             writeFileSync(output, `${JSON.stringify(config, null, 2)}\n`);
             writeFileSync(promptOutput, `${DEFAULT_SYSTEM_PROMPT}\n`);
             const resolvedConfig = readConfig(output);
@@ -657,33 +1085,41 @@ Step 5: Follow the generated setup guide
 Next command:
   npx @nexalink/carecompass-sdk validate --config ${output}
 `);
+            await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_INIT_COMPLETED, {
+                initDurationMs: Date.now() - initStartedAt,
+                authMethod: initAuth.authMethod,
+                baaStatus: initAuth.baaStatus,
+            });
             await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_SETUP_KIT_GENERATED);
+            await captureCommandCompleted();
             return 0;
         }
         if (command === "validate") {
             try {
-                const credentials = requireApiKey(flags, io);
-                const config = readConfig(flagString(flags, "config") ?? DEFAULT_CONFIG_PATH);
-                cliTelemetry = createCareCompassCliTelemetry(cliSessionId, config);
+                const { config, credentials } = await authenticateConfigCommand(flags);
+                await captureCommandStarted();
                 if (flags["local-only"] !== true) {
                     await assertHostedConfig(config, credentials.apiKey);
                 }
                 io.stdout.write(`CareCompass config is valid for ${config.payerId}. Credentials loaded from ${credentials.source}.\n`);
                 await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_VALIDATION_SUCCEEDED);
+                await captureCommandCompleted();
                 return 0;
             }
             catch (error) {
-                await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_VALIDATION_FAILED, {
-                    errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CLI_COMMAND_FAILED,
-                    failureCategory: "configuration",
-                });
+                const failure = classifyCliFailure(error);
+                if (commandStartedCaptured) {
+                    await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_VALIDATION_FAILED, {
+                        errorCode: failure.errorCode,
+                        failureCategory: failure.failureCategory,
+                    });
+                }
                 throw error;
             }
         }
         if (command === "snippet") {
-            requireApiKey(flags, io);
-            const config = readConfig(flagString(flags, "config") ?? DEFAULT_CONFIG_PATH);
-            cliTelemetry = createCareCompassCliTelemetry(cliSessionId, config);
+            const { config } = await authenticateConfigCommand(flags);
+            await captureCommandStarted();
             const snippet = generateCareCompassSnippet(runtimeConfig(config), {
                 mode: snippetMode(flags),
             });
@@ -697,12 +1133,12 @@ Next command:
                 io.stdout.write(`${snippet}\n`);
             }
             await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_SNIPPET_GENERATED);
+            await captureCommandCompleted();
             return 0;
         }
         if (command === "doctor") {
-            const credentials = requireApiKey(flags, io);
-            const config = readConfig(flagString(flags, "config") ?? DEFAULT_CONFIG_PATH);
-            cliTelemetry = createCareCompassCliTelemetry(cliSessionId, config);
+            const { config, credentials } = await authenticateConfigCommand(flags);
+            await captureCommandStarted();
             let hostedStatus = "not checked";
             try {
                 await assertHostedConfig(config, credentials.apiKey);
@@ -723,24 +1159,35 @@ Hosted API: ${hostedStatus}
 Status: ready for staging verification
 `);
             await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_DOCTOR_COMPLETED);
+            await captureCommandCompleted();
             return 0;
         }
+        await captureCommandStarted();
         throw new Error(`Unknown command: ${command}`);
     }
     catch (error) {
-        if (activeCommand === "init") {
+        commandsFailed += 1;
+        if (!commandStartedCaptured && commandsAttempted === 0) {
+            commandsAttempted = 1;
+        }
+        const failure = classifyCliFailure(error);
+        if (activeCommand === "init" && initStartedCaptured) {
             await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_INIT_FAILED, {
-                errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CLI_COMMAND_FAILED,
-                failureCategory: "unknown",
+                errorCode: failure.errorCode,
+                failureCategory: failure.failureCategory,
             });
         }
         await cliTelemetry.captureAsync(CARECOMPASS_TELEMETRY_EVENTS.CLI_COMMAND_FAILED, {
-            errorCode: CARECOMPASS_TELEMETRY_ERROR_CODES.CLI_COMMAND_FAILED,
-            failureCategory: "unknown",
+            errorCode: failure.errorCode,
+            failureCategory: failure.failureCategory,
+            commandName: telemetryCommandName,
         });
         io.stderr.write(`${error.message}\n`);
         return 1;
     }
+    finally {
+        await captureSessionEnded(commandsFailed > 0 ? "error" : "user_exit");
+    }
 }
 const isMainModule = () => Boolean(process.argv[1]) &&
     realpathSync(fileURLToPath(import.meta.url)) ===