@mcoda/core 0.1.38 → 0.1.40

package/dist/api/MswarmApi.js

@@ -1,17 +1,27 @@
-import { GlobalRepository } from "@mcoda/db";
-import { CryptoHelper, } from "@mcoda/shared";
-import { MswarmConfigStore } from "./MswarmConfigStore.js";
-const DEFAULT_BASE_URL = "https://api.mswarm.org/";
+import { GlobalRepository } from '@mcoda/db';
+import { CryptoHelper, } from '@mcoda/shared';
+import { MswarmConfigStore } from './MswarmConfigStore.js';
+const DEFAULT_BASE_URL = 'https://api.mswarm.org/';
 const DEFAULT_TIMEOUT_MS = 15000;
-const DEFAULT_AGENT_SLUG_PREFIX = "mswarm-cloud";
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const resolveString = (value) => typeof value === "string" && value.trim() ? value : undefined;
-const resolveNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
-const resolveBoolean = (value) => typeof value === "boolean" ? value : undefined;
+const DEFAULT_AGENT_SLUG_PREFIX = 'mswarm-cloud';
+export const MSWARM_CONSENT_POLICY_VERSION = '2026-03-18';
+export const MCODA_FREE_CLIENT_TYPE = 'free_mcoda_client';
+const MCODA_PRODUCT_SLUG = 'mcoda';
+const MCODA_CONSENT_TYPES = ['anonymous', 'non_anonymous'];
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const resolveString = (value) => typeof value === 'string' && value.trim() ? value : undefined;
+const resolveNumber = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+const resolveBoolean = (value) => typeof value === 'boolean' ? value : undefined;
+const resolveTimestamp = (value) => {
+    const candidate = resolveString(value);
+    if (!candidate)
+        return undefined;
+    return Number.isNaN(Date.parse(candidate)) ? undefined : candidate;
+};
 const resolveStringArray = (value) => {
     if (!Array.isArray(value))
         return [];
-    return value.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+    return value.filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
 };
 const normalizeBaseUrl = (value, label) => {
     const trimmed = value?.trim();
@@ -35,9 +45,27 @@ const normalizePositiveInt = (value, label, fallback) => {
     }
     return Math.trunc(value);
 };
+const normalizeOptionalPositiveInt = (value, label) => {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`${label} must be a positive integer`);
+    }
+    return Math.trunc(value);
+};
+const normalizeOptionalNonNegativeNumber = (value, label) => {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`${label} must be a non-negative number`);
+    }
+    return value;
+};
 const resolveOptions = async (options = {}) => {
     const envTimeoutRaw = process.env.MCODA_MSWARM_TIMEOUT_MS;
-    const envTimeout = envTimeoutRaw ? Number.parseInt(envTimeoutRaw, 10) : undefined;
+    const envTimeout = envTimeoutRaw
+        ? Number.parseInt(envTimeoutRaw, 10)
+        : undefined;
     const directBaseUrl = options.baseUrl ?? process.env.MCODA_MSWARM_BASE_URL;
     const directOpenAiBaseUrl = options.openAiBaseUrl ?? process.env.MCODA_MSWARM_OPENAI_BASE_URL;
     const directApiKey = options.apiKey ?? process.env.MCODA_MSWARM_API_KEY;
@@ -47,40 +75,140 @@ const resolveOptions = async (options = {}) => {
         directApiKey === undefined ||
         directTimeout === undefined ||
         directAgentSlugPrefix === undefined;
-    const stored = needsStoredFallback ? await new MswarmConfigStore().readState() : {};
+    const stored = needsStoredFallback
+        ? await new MswarmConfigStore().readState()
+        : {};
     return {
-        baseUrl: normalizeBaseUrl(directBaseUrl ?? stored.baseUrl ?? DEFAULT_BASE_URL, "MCODA_MSWARM_BASE_URL"),
+        baseUrl: normalizeBaseUrl(directBaseUrl ?? stored.baseUrl ?? DEFAULT_BASE_URL, 'MCODA_MSWARM_BASE_URL'),
         openAiBaseUrl: directOpenAiBaseUrl
-            ? normalizeBaseUrl(directOpenAiBaseUrl, "MCODA_MSWARM_OPENAI_BASE_URL")
+            ? normalizeBaseUrl(directOpenAiBaseUrl, 'MCODA_MSWARM_OPENAI_BASE_URL')
             : undefined,
-        apiKey: resolveString(directApiKey ?? stored.apiKey) ?? (() => {
-            throw new Error("MCODA_MSWARM_API_KEY is required");
-        })(),
-        timeoutMs: normalizePositiveInt(directTimeout ?? stored.timeoutMs, "MCODA_MSWARM_TIMEOUT_MS", DEFAULT_TIMEOUT_MS),
-        agentSlugPrefix: resolveString(directAgentSlugPrefix ?? stored.agentSlugPrefix) ?? DEFAULT_AGENT_SLUG_PREFIX,
+        apiKey: resolveString(directApiKey ?? stored.apiKey),
+        timeoutMs: normalizePositiveInt(directTimeout ?? stored.timeoutMs, 'MCODA_MSWARM_TIMEOUT_MS', DEFAULT_TIMEOUT_MS),
+        agentSlugPrefix: resolveString(directAgentSlugPrefix ?? stored.agentSlugPrefix) ??
+            DEFAULT_AGENT_SLUG_PREFIX,
     };
 };
 const uniqueStrings = (values) => Array.from(new Set(values.filter((value) => value.trim().length > 0)));
+const resolveFromRecordOrShape = (record, keys, parser) => {
+    const sources = [
+        record,
+        isRecord(record.mcoda_shape) ? record.mcoda_shape : undefined,
+    ].filter(isRecord);
+    for (const source of sources) {
+        for (const key of keys) {
+            const resolved = parser(source[key]);
+            if (resolved !== undefined)
+                return resolved;
+        }
+    }
+    return undefined;
+};
+const resolveStringArrayFromRecordOrShape = (record, keys) => {
+    const sources = [
+        record,
+        isRecord(record.mcoda_shape) ? record.mcoda_shape : undefined,
+    ].filter(isRecord);
+    const values = sources.flatMap((source) => keys.flatMap((key) => resolveStringArray(source[key])));
+    return uniqueStrings(values);
+};
+const hasCapabilityFragment = (capabilities, fragments) => capabilities.some((capability) => fragments.some((fragment) => capability.includes(fragment)));
+const inferCloudBestUsage = (agent) => {
+    const capabilities = agent.capabilities.map((capability) => capability.trim().toLowerCase());
+    const model = agent.default_model.trim().toLowerCase();
+    if (hasCapabilityFragment(capabilities, ['code_review', 'review']))
+        return 'code_review';
+    if (hasCapabilityFragment(capabilities, ['qa', 'test']))
+        return 'qa_testing';
+    if (hasCapabilityFragment(capabilities, ['research', 'search', 'discover']))
+        return 'deep_research';
+    if (hasCapabilityFragment(capabilities, [
+        'code_write',
+        'coding',
+        'tool_runner',
+        'iterative_coding',
+        'structured_output',
+    ]) ||
+        model.includes('codex')) {
+        return 'code_write';
+    }
+    if (hasCapabilityFragment(capabilities, ['architect', 'plan']))
+        return 'system_architecture';
+    if (hasCapabilityFragment(capabilities, ['doc']))
+        return 'doc_generation';
+    return 'general';
+};
+const DEFAULT_CONTEXT_WINDOW = 8192;
+const DEFAULT_MAX_OUTPUT_TOKENS = 2048;
+const DEFAULT_MAX_COMPLEXITY = 5;
+const toSyncedAgentInput = (existing, agent, localSlug, config, syncedAt) => {
+    const rating = existing?.rating ?? agent.rating;
+    const reasoningRating = existing?.reasoningRating ?? agent.reasoning_rating ?? rating;
+    const maxComplexity = existing?.maxComplexity ?? agent.max_complexity ?? DEFAULT_MAX_COMPLEXITY;
+    const ratingSamples = existing?.ratingSamples ?? agent.rating_samples ?? 0;
+    const ratingLastScore = existing?.ratingLastScore ?? agent.rating_last_score ?? rating;
+    const ratingUpdatedAt = existing?.ratingUpdatedAt ?? agent.rating_updated_at ?? syncedAt;
+    const complexitySamples = existing?.complexitySamples ?? agent.complexity_samples ?? 0;
+    const complexityUpdatedAt = existing?.complexityUpdatedAt ?? agent.complexity_updated_at ?? syncedAt;
+    return {
+        slug: localSlug,
+        adapter: 'openai-api',
+        defaultModel: agent.default_model,
+        openaiCompatible: true,
+        contextWindow: agent.context_window ?? existing?.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+        maxOutputTokens: agent.max_output_tokens ??
+            existing?.maxOutputTokens ??
+            DEFAULT_MAX_OUTPUT_TOKENS,
+        supportsTools: agent.supports_tools,
+        rating,
+        reasoningRating,
+        bestUsage: agent.best_usage ?? existing?.bestUsage ?? inferCloudBestUsage(agent),
+        costPerMillion: agent.cost_per_million ?? existing?.costPerMillion,
+        maxComplexity,
+        ratingSamples,
+        ratingLastScore,
+        ratingUpdatedAt,
+        complexitySamples,
+        complexityUpdatedAt,
+        config,
+        capabilities: uniqueStrings(agent.capabilities),
+    };
+};
 const toManagedLocalSlug = (prefix, remoteSlug) => {
     const normalized = remoteSlug
         .trim()
         .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "");
-    return `${prefix}-${normalized || "agent"}`;
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return `${prefix}-${normalized || 'agent'}`;
 };
 const toHealthStatus = (value) => {
     const normalized = value?.trim().toLowerCase();
     if (!normalized)
         return undefined;
-    if (normalized === "healthy")
-        return "healthy";
-    if (normalized === "degraded" || normalized === "unknown" || normalized === "limited")
-        return "degraded";
-    if (normalized === "unreachable" || normalized === "offline")
-        return "unreachable";
+    if (normalized === 'healthy')
+        return 'healthy';
+    if (normalized === 'degraded' ||
+        normalized === 'unknown' ||
+        normalized === 'limited')
+        return 'degraded';
+    if (normalized === 'unreachable' || normalized === 'offline')
+        return 'unreachable';
     return undefined;
 };
+const isSyncManagedHealth = (health) => isRecord(health?.details) &&
+    (health.details.source === 'mswarm' ||
+        health.details.source === 'mswarm_catalog');
+const isAuthMissingManagedHealth = (health) => {
+    if (!isRecord(health?.details))
+        return false;
+    const reason = resolveString(health.details.reason);
+    const error = resolveString(health.details.error) ?? '';
+    return (reason === 'missing_api_key' ||
+        /AUTH_REQUIRED/i.test(error) ||
+        /missing the synced API key/i.test(error));
+};
+const shouldReplaceManagedHealth = (health) => !health || isSyncManagedHealth(health) || isAuthMissingManagedHealth(health);
 const isManagedMswarmConfig = (config) => {
     if (!isRecord(config))
         return false;
@@ -111,35 +239,50 @@ const toManagedConfig = (existingConfig, catalogBaseUrl, openAiBaseUrl, agent, s
     };
     return nextConfig;
 };
+const toManagedSyncRecord = (config, localSlug, defaultModel, action) => ({
+    remoteSlug: config.mswarmCloud.remoteSlug,
+    localSlug,
+    action,
+    provider: config.mswarmCloud.provider,
+    defaultModel,
+    pricingVersion: config.mswarmCloud.pricingVersion,
+});
 const toCloudAgent = (value) => {
     if (!isRecord(value)) {
-        throw new Error("mswarm returned an invalid cloud-agent payload");
+        throw new Error('mswarm returned an invalid cloud-agent payload');
     }
-    const slug = resolveString(value.slug);
-    const provider = resolveString(value.provider);
-    const defaultModel = resolveString(value.default_model);
-    const supportsTools = resolveBoolean(value.supports_tools);
+    const slug = resolveFromRecordOrShape(value, ['slug'], resolveString);
+    const provider = resolveFromRecordOrShape(value, ['provider'], resolveString);
+    const defaultModel = resolveFromRecordOrShape(value, ['default_model', 'defaultModel'], resolveString);
+    const supportsTools = resolveFromRecordOrShape(value, ['supports_tools', 'supportsTools'], resolveBoolean);
     if (!slug || !provider || !defaultModel || supportsTools === undefined) {
-        throw new Error("mswarm cloud-agent payload is missing required fields");
+        throw new Error('mswarm cloud-agent payload is missing required fields');
     }
     return {
         slug,
         provider,
         default_model: defaultModel,
-        cost_per_million: resolveNumber(value.cost_per_million),
-        rating: resolveNumber(value.rating),
-        reasoning_rating: resolveNumber(value.reasoning_rating),
-        max_complexity: resolveNumber(value.max_complexity),
-        capabilities: resolveStringArray(value.capabilities),
-        health_status: resolveString(value.health_status),
-        context_window: resolveNumber(value.context_window),
+        cost_per_million: resolveFromRecordOrShape(value, ['cost_per_million', 'costPerMillion'], resolveNumber),
+        rating: resolveFromRecordOrShape(value, ['rating'], resolveNumber),
+        reasoning_rating: resolveFromRecordOrShape(value, ['reasoning_rating', 'reasoningRating'], resolveNumber),
+        max_complexity: resolveFromRecordOrShape(value, ['max_complexity', 'maxComplexity'], resolveNumber),
+        capabilities: resolveStringArrayFromRecordOrShape(value, ['capabilities']),
+        health_status: resolveFromRecordOrShape(value, ['health_status', 'healthStatus'], resolveString),
+        context_window: resolveFromRecordOrShape(value, ['context_window', 'contextWindow'], resolveNumber),
+        max_output_tokens: resolveFromRecordOrShape(value, ['max_output_tokens', 'maxOutputTokens'], resolveNumber),
         supports_tools: supportsTools,
-        model_id: resolveString(value.model_id),
-        display_name: resolveString(value.display_name),
-        description: resolveString(value.description),
-        supports_reasoning: resolveBoolean(value.supports_reasoning),
-        pricing_snapshot_id: resolveString(value.pricing_snapshot_id),
-        pricing_version: resolveString(value.pricing_version),
+        best_usage: resolveFromRecordOrShape(value, ['best_usage', 'bestUsage'], resolveString),
+        model_id: resolveFromRecordOrShape(value, ['model_id', 'modelId'], resolveString),
+        display_name: resolveFromRecordOrShape(value, ['display_name', 'displayName'], resolveString),
+        description: resolveFromRecordOrShape(value, ['description'], resolveString),
+        supports_reasoning: resolveFromRecordOrShape(value, ['supports_reasoning', 'supportsReasoning'], resolveBoolean),
+        pricing_snapshot_id: resolveFromRecordOrShape(value, ['pricing_snapshot_id', 'pricingSnapshotId'], resolveString),
+        pricing_version: resolveFromRecordOrShape(value, ['pricing_version', 'pricingVersion'], resolveString),
+        rating_samples: resolveFromRecordOrShape(value, ['rating_samples', 'ratingSamples'], resolveNumber),
+        rating_last_score: resolveFromRecordOrShape(value, ['rating_last_score', 'ratingLastScore'], resolveNumber),
+        rating_updated_at: resolveFromRecordOrShape(value, ['rating_updated_at', 'ratingUpdatedAt'], resolveTimestamp),
+        complexity_samples: resolveFromRecordOrShape(value, ['complexity_samples', 'complexitySamples'], resolveNumber),
+        complexity_updated_at: resolveFromRecordOrShape(value, ['complexity_updated_at', 'complexityUpdatedAt'], resolveTimestamp),
         sync: isRecord(value.sync) ? value.sync : undefined,
     };
 };
@@ -155,6 +298,43 @@ const toCloudAgentDetail = (value) => {
         mcoda_shape: isRecord(record.mcoda_shape) ? record.mcoda_shape : undefined,
     };
 };
+const hasAdvancedCloudAgentSelection = (options) => options.maxCostPerMillion !== undefined ||
+    options.minContextWindow !== undefined ||
+    options.minReasoningRating !== undefined ||
+    options.sortByCatalogRating === true;
+const sortCloudAgentsByCatalogRating = (agents) => [...agents].sort((left, right) => {
+    const ratingDelta = (right.rating ?? Number.NEGATIVE_INFINITY) -
+        (left.rating ?? Number.NEGATIVE_INFINITY);
+    if (ratingDelta !== 0)
+        return ratingDelta;
+    return left.slug.localeCompare(right.slug);
+});
+const applyCloudAgentListOptions = (agents, options) => {
+    const maxCostPerMillion = normalizeOptionalNonNegativeNumber(options.maxCostPerMillion, 'maxCostPerMillion');
+    const minContextWindow = normalizeOptionalPositiveInt(options.minContextWindow, 'minContextWindow');
+    const minReasoningRating = normalizeOptionalNonNegativeNumber(options.minReasoningRating, 'minReasoningRating');
+    const limit = normalizeOptionalPositiveInt(options.limit, 'limit');
+    let next = [...agents];
+    if (maxCostPerMillion !== undefined) {
+        next = next.filter((agent) => agent.cost_per_million !== undefined &&
+            agent.cost_per_million <= maxCostPerMillion);
+    }
+    if (minContextWindow !== undefined) {
+        next = next.filter((agent) => agent.context_window !== undefined &&
+            agent.context_window >= minContextWindow);
+    }
+    if (minReasoningRating !== undefined) {
+        next = next.filter((agent) => agent.reasoning_rating !== undefined &&
+            agent.reasoning_rating >= minReasoningRating);
+    }
+    if (options.sortByCatalogRating) {
+        next = sortCloudAgentsByCatalogRating(next);
+    }
+    if (limit !== undefined) {
+        next = next.slice(0, limit);
+    }
+    return next;
+};
 const toAgentModels = (agentId, entry) => [
     {
         agentId,
@@ -179,10 +359,41 @@ export class MswarmApi {
         const repo = await GlobalRepository.create();
         return new MswarmApi(repo, await resolveOptions(options));
     }
+    static async refreshManagedAgentAuth(apiKey) {
+        const trimmed = apiKey.trim();
+        if (!trimmed) {
+            throw new Error('mswarm api key is required');
+        }
+        const repo = await GlobalRepository.create();
+        try {
+            const encryptedApiKey = await CryptoHelper.encryptSecret(trimmed);
+            const agents = await repo.listAgents();
+            const managedAgents = agents.filter((agent) => isManagedMswarmConfig(agent.config));
+            for (const agent of managedAgents) {
+                await repo.setAgentAuth(agent.id, encryptedApiKey);
+            }
+            return {
+                updated: managedAgents.length,
+                agents: managedAgents.map((agent) => agent.slug),
+            };
+        }
+        finally {
+            await repo.close();
+        }
+    }
     async close() {
         await this.repo.close();
     }
-    async requestJson(pathname, query) {
+    async refreshManagedAgentAuth() {
+        return MswarmApi.refreshManagedAgentAuth(this.requireApiKey());
+    }
+    requireApiKey() {
+        if (!this.options.apiKey) {
+            throw new Error('MCODA_MSWARM_API_KEY is required');
+        }
+        return this.options.apiKey;
+    }
+    async requestJson(pathname, query, init) {
         const url = new URL(pathname, this.options.baseUrl);
         if (query) {
             for (const [key, value] of Object.entries(query)) {
@@ -194,15 +405,26 @@ export class MswarmApi {
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), this.options.timeoutMs);
         try {
+            const headers = {
+                accept: 'application/json',
+                ...(init?.headers ?? {}),
+            };
+            if (this.options.apiKey) {
+                headers['x-api-key'] = this.options.apiKey;
+            }
+            let body;
+            if (init?.body !== undefined) {
+                headers['content-type'] = 'application/json';
+                body = JSON.stringify(init.body);
+            }
             const response = await fetch(url.toString(), {
-                headers: {
-                    accept: "application/json",
-                    "x-api-key": this.options.apiKey,
-                },
+                method: init?.method ?? 'GET',
+                headers,
+                body,
                 signal: controller.signal,
             });
             if (!response.ok) {
-                const body = await response.text().catch(() => "");
+                const body = await response.text().catch(() => '');
                 throw new Error(`mswarm request failed (${response.status}): ${body || response.statusText}`);
             }
             try {
@@ -213,7 +435,7 @@ export class MswarmApi {
             }
         }
         catch (error) {
-            if (error instanceof Error && error.name === "AbortError") {
+            if (error instanceof Error && error.name === 'AbortError') {
                 throw new Error(`mswarm request timed out after ${this.options.timeoutMs}ms`);
             }
             throw error;
@@ -223,84 +445,149 @@ export class MswarmApi {
         }
     }
     async listCloudAgents(options = {}) {
-        const payload = await this.requestJson("/v1/swarm/cloud/agents", {
-            shape: "mcoda",
+        const remoteLimit = hasAdvancedCloudAgentSelection(options)
+            ? undefined
+            : options.limit;
+        const payload = await this.requestJson('/v1/swarm/cloud/agents', {
+            shape: 'mcoda',
             provider: options.provider,
-            limit: options.limit,
+            limit: remoteLimit,
         });
         const agents = Array.isArray(payload.agents) ? payload.agents : [];
-        return agents.map(toCloudAgent);
+        return applyCloudAgentListOptions(agents.map(toCloudAgent), options);
     }
     async getCloudAgent(slug) {
         if (!slug.trim()) {
-            throw new Error("Cloud-agent slug is required");
+            throw new Error('Cloud-agent slug is required');
         }
         const payload = await this.requestJson(`/v1/swarm/cloud/agents/${encodeURIComponent(slug)}`);
         return toCloudAgentDetail(payload);
     }
     async syncCloudAgents(options = {}) {
+        if (options.pruneMissing &&
+            (options.limit !== undefined || hasAdvancedCloudAgentSelection(options))) {
+            throw new Error('pruneMissing cannot be combined with limit or advanced cloud-agent filters');
+        }
         const agents = await this.listCloudAgents(options);
-        const openAiBaseUrl = this.options.openAiBaseUrl ?? new URL("/v1/swarm/openai/", this.options.baseUrl).toString();
+        const openAiBaseUrl = this.options.openAiBaseUrl ??
+            new URL('/v1/swarm/openai/', this.options.baseUrl).toString();
         const syncedAt = new Date().toISOString();
-        const encryptedApiKey = await CryptoHelper.encryptSecret(this.options.apiKey);
+        const encryptedApiKey = await CryptoHelper.encryptSecret(this.requireApiKey());
         const records = [];
         for (const agent of agents) {
             const localSlug = toManagedLocalSlug(this.options.agentSlugPrefix, agent.slug);
             const existing = await this.repo.getAgentBySlug(localSlug);
-            if (existing && (!isManagedMswarmConfig(existing.config) || existing.config.mswarmCloud.remoteSlug !== agent.slug)) {
+            if (existing &&
+                (!isManagedMswarmConfig(existing.config) ||
+                    existing.config.mswarmCloud.remoteSlug !== agent.slug)) {
                 throw new Error(`Refusing to overwrite non-mswarm agent ${localSlug}`);
             }
-            const existingConfig = existing && isRecord(existing.config) ? existing.config : undefined;
+            const existingConfig = existing && isRecord(existing.config)
+                ? existing.config
+                : undefined;
             const nextConfig = toManagedConfig(existingConfig, this.options.baseUrl, openAiBaseUrl, agent, syncedAt);
-            const baseInput = {
-                slug: localSlug,
-                adapter: "openai-api",
-                defaultModel: agent.default_model,
-                openaiCompatible: true,
-                contextWindow: agent.context_window,
-                supportsTools: agent.supports_tools,
-                rating: agent.rating,
-                reasoningRating: agent.reasoning_rating,
-                costPerMillion: agent.cost_per_million,
-                maxComplexity: agent.max_complexity,
-                config: nextConfig,
-                capabilities: uniqueStrings(agent.capabilities),
-            };
+            const createInput = toSyncedAgentInput(existing, agent, localSlug, nextConfig, syncedAt);
+            const { slug: _ignoredSlug, ...updateInput } = createInput;
             const stored = existing
-                ? await this.repo.updateAgent(existing.id, baseInput)
-                : await this.repo.createAgent(baseInput);
+                ? await this.repo.updateAgent(existing.id, updateInput)
+                : await this.repo.createAgent(createInput);
             if (!stored) {
                 throw new Error(`Failed to persist synced agent ${localSlug}`);
             }
             await this.repo.setAgentModels(stored.id, toAgentModels(stored.id, agent));
             await this.repo.setAgentAuth(stored.id, encryptedApiKey);
+            const existingHealth = existing
+                ? await this.repo.getAgentHealth(existing.id)
+                : undefined;
             const mappedHealth = toHealthStatus(agent.health_status);
-            if (mappedHealth) {
+            if (mappedHealth && shouldReplaceManagedHealth(existingHealth)) {
                 const health = {
                     agentId: stored.id,
                     status: mappedHealth,
                     lastCheckedAt: syncedAt,
                     details: {
-                        source: "mswarm",
+                        source: 'mswarm',
                         remoteSlug: agent.slug,
                         remoteHealthStatus: agent.health_status,
                     },
                 };
                 await this.repo.setAgentHealth(health);
             }
-            records.push({
-                remoteSlug: agent.slug,
-                localSlug,
-                action: existing ? "updated" : "created",
-                provider: agent.provider,
-                defaultModel: agent.default_model,
-                pricingVersion: agent.pricing_version,
-            });
+            records.push(toManagedSyncRecord(nextConfig, localSlug, agent.default_model, existing ? 'updated' : 'created'));
+        }
+        if (options.pruneMissing) {
+            const remoteSlugs = new Set(agents.map((agent) => agent.slug));
+            const localAgents = await this.repo.listAgents();
+            for (const localAgent of localAgents) {
+                const managedConfig = isManagedMswarmConfig(localAgent.config)
+                    ? localAgent.config
+                    : undefined;
+                if (!managedConfig)
+                    continue;
+                if (options.provider &&
+                    managedConfig.mswarmCloud.provider !== options.provider) {
+                    continue;
+                }
+                if (remoteSlugs.has(managedConfig.mswarmCloud.remoteSlug))
+                    continue;
+                await this.repo.deleteAgent(localAgent.id);
+                records.push(toManagedSyncRecord(managedConfig, localAgent.slug, localAgent.defaultModel ?? managedConfig.mswarmCloud.modelId ?? '-', 'deleted'));
+            }
         }
         return {
-            created: records.filter((record) => record.action === "created").length,
-            updated: records.filter((record) => record.action === "updated").length,
+            created: records.filter((record) => record.action === 'created').length,
+            updated: records.filter((record) => record.action === 'updated').length,
+            deleted: records.filter((record) => record.action === 'deleted').length,
             agents: records,
         };
     }
+    async issuePaidConsent(policyVersion = MSWARM_CONSENT_POLICY_VERSION) {
+        const apiKey = this.requireApiKey();
+        return this.requestJson('/v1/swarm/consent/issue', undefined, {
+            method: 'POST',
+            body: {
+                consent_types: [...MCODA_CONSENT_TYPES],
+                policy_version: policyVersion,
+                timestamp_ms: Date.now(),
+                proof: {
+                    type: 'api_key',
+                    value: apiKey,
+                },
+            },
+        });
+    }
+    async registerFreeMcodaClient(options) {
+        return this.requestJson('/v1/swarm/mcoda/free-client/register', undefined, {
+            method: 'POST',
+            body: {
+                client_id: options.clientId,
+                product: MCODA_PRODUCT_SLUG,
+                product_version: options.productVersion,
+                policy_version: options.policyVersion ?? MSWARM_CONSENT_POLICY_VERSION,
+                timestamp_ms: Date.now(),
+                consent_types: [...MCODA_CONSENT_TYPES],
+            },
+        });
+    }
+    async revokeConsent(consentToken, reason) {
+        return this.requestJson('/v1/swarm/consent/revoke', undefined, {
+            method: 'POST',
+            body: {
+                consent_token: consentToken,
+                reason,
+            },
+        });
+    }
+    async requestDataDeletion(input) {
+        return this.requestJson('/v1/swarm/data/deletion-request', undefined, {
+            method: 'POST',
+            body: {
+                consent_token: input.consentToken,
+                product: input.product,
+                client_id: input.clientId,
+                client_type: input.clientType,
+                reason: input.reason,
+            },
+        });
+    }
 }

package/dist/api/MswarmConfigStore.d.ts

@@ -3,6 +3,14 @@ export interface StoredMswarmConfigState {
     encryptedApiKey?: string;
     timeoutMs?: number;
     agentSlugPrefix?: string;
+    consentAccepted?: boolean;
+    consentPolicyVersion?: string;
+    consentToken?: string;
+    clientId?: string;
+    clientType?: string;
+    registeredAtMs?: number;
+    uploadSigningSecret?: string;
+    deletionRequestedAtMs?: number;
 }
 export interface MswarmConfigFileState extends Record<string, unknown> {
     mswarm?: StoredMswarmConfigState;
@@ -12,6 +20,24 @@ export interface MswarmConfigState {
     apiKey?: string;
     timeoutMs?: number;
     agentSlugPrefix?: string;
+    consentAccepted?: boolean;
+    consentPolicyVersion?: string;
+    consentToken?: string;
+    clientId?: string;
+    clientType?: string;
+    registeredAtMs?: number;
+    uploadSigningSecret?: string;
+    deletionRequestedAtMs?: number;
+}
+export interface MswarmConsentState {
+    consentAccepted: boolean;
+    consentPolicyVersion?: string;
+    consentToken?: string;
+    clientId?: string;
+    clientType?: string;
+    registeredAtMs?: number;
+    uploadSigningSecret?: string;
+    deletionRequestedAtMs?: number;
 }
 export declare class MswarmConfigStore {
     private readonly configFilePath;
@@ -19,6 +45,8 @@ export declare class MswarmConfigStore {
     configPath(): string;
     readState(): Promise<MswarmConfigState>;
     saveApiKey(apiKey: string): Promise<MswarmConfigState>;
+    saveConsentState(consent: MswarmConsentState): Promise<MswarmConfigState>;
+    clearConsentState(): Promise<MswarmConfigState>;
     private readConfigFile;
     private writeConfigFile;
 }

package/dist/api/MswarmConfigStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MswarmConfigStore.d.ts","sourceRoot":"","sources":["../../src/api/MswarmConfigStore.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAsB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACpE,MAAM,CAAC,EAAE,uBAAuB,CAAC;CAClC;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,cAAc;gBAAd,cAAc,GAAE,MAAyC;IAEtF,UAAU,IAAI,MAAM;IAId,SAAS,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAqBvC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;YAiB9C,cAAc;YAad,eAAe;CAI9B"}
+{"version":3,"file":"MswarmConfigStore.d.ts","sourceRoot":"","sources":["../../src/api/MswarmConfigStore.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,qBAAsB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACpE,MAAM,CAAC,EAAE,uBAAuB,CAAC;CAClC;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,eAAe,EAAE,OAAO,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,QAAQ,CAAC,cAAc;gBAAd,cAAc,GAAE,MAAyC;IAG5E,UAAU,IAAI,MAAM;IAId,SAAS,IAAI,OAAO,CAAC,iBAAiB,CAAC;IA6BvC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAiBtD,gBAAgB,CACpB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC;IAyBvB,iBAAiB,IAAI,OAAO,CAAC,iBAAiB,CAAC;YAcvC,cAAc;YAad,eAAe;CAQ9B"}