@taskforcehq/taskforce 0.3.306 → 0.3.308

package/dist/core/AiProfileService.js

@@ -22,6 +22,17 @@ function normalizeOptionalProfileField(value) {
 function normalizeAiProfileAvatarUrl(value) {
     return normalizeSyncSameOriginAssetUrl(value);
 }
+function normalizeAiProfileAvatarRevision(value) {
+    if (value === undefined || value === null || value === '')
+        return 0;
+    const normalized = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(normalized))
+        return 0;
+    return Math.max(0, Math.floor(normalized));
+}
+function hasAiProfileAvatarState(avatarUrl, avatarSourceUrl) {
+    return Boolean(avatarUrl || avatarSourceUrl);
+}
 function compareIsoStrings(left, right) {
     const normalizedLeft = normalizeNullableIsoString(left);
     const normalizedRight = normalizeNullableIsoString(right);
@@ -53,16 +64,73 @@ function normalizeAiProfileSurfaceTypeInput(deps, value) {
     if (value === null)
         return null;
     if (typeof value !== 'string') {
-        throw deps.createRuleError('AI profile surfaceType must be one of chat_app, ide, coding_tool, agent, or other', 400, 'AI_PROFILE_SURFACE_TYPE_INVALID');
+        throw deps.createRuleError('AI profile surfaceType must be one of chat_app, ide, cli, coding_tool, or agent', 400, 'AI_PROFILE_SURFACE_TYPE_INVALID');
     }
     const normalized = value.trim();
     if (!normalized)
         return null;
+    if (normalized === 'other')
+        return 'agent';
     if (!isAiProfileSurfaceType(normalized)) {
-        throw deps.createRuleError('AI profile surfaceType must be one of chat_app, ide, coding_tool, agent, or other', 400, 'AI_PROFILE_SURFACE_TYPE_INVALID');
+        throw deps.createRuleError('AI profile surfaceType must be one of chat_app, ide, cli, coding_tool, or agent', 400, 'AI_PROFILE_SURFACE_TYPE_INVALID');
     }
     return normalized;
 }
+function readAiProfileProviderMetadataJson(value) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function hasManualSurfaceTypeOverride(profile) {
+    const taskforceMetadata = profile?.providerMetadata?.taskforce;
+    return Boolean(taskforceMetadata
+        && typeof taskforceMetadata === 'object'
+        && !Array.isArray(taskforceMetadata)
+        && taskforceMetadata.surfaceTypeManuallySet === true);
+}
+function markManualSurfaceTypeOverride(row) {
+    const metadata = readAiProfileProviderMetadataJson(row.provider_metadata_json) ?? {};
+    const taskforceMetadata = metadata.taskforce && typeof metadata.taskforce === 'object' && !Array.isArray(metadata.taskforce)
+        ? metadata.taskforce
+        : {};
+    return JSON.stringify({
+        ...metadata,
+        taskforce: {
+            ...taskforceMetadata,
+            surfaceTypeManuallySet: true
+        }
+    });
+}
+function clearManualSurfaceTypeOverride(row) {
+    const metadata = readAiProfileProviderMetadataJson(row.provider_metadata_json);
+    if (!metadata)
+        return null;
+    const taskforceMetadata = metadata.taskforce && typeof metadata.taskforce === 'object' && !Array.isArray(metadata.taskforce)
+        ? { ...metadata.taskforce }
+        : null;
+    if (!taskforceMetadata || taskforceMetadata.surfaceTypeManuallySet !== true) {
+        return JSON.stringify(metadata);
+    }
+    delete taskforceMetadata.surfaceTypeManuallySet;
+    const nextMetadata = { ...metadata };
+    if (Object.keys(taskforceMetadata).length > 0) {
+        nextMetadata.taskforce = taskforceMetadata;
+    }
+    else {
+        delete nextMetadata.taskforce;
+    }
+    return Object.keys(nextMetadata).length > 0
+        ? JSON.stringify(nextMetadata)
+        : null;
+}
 function normalizeAiProfileSeatScopeInput(deps, value) {
     if (value === undefined)
         return undefined;
@@ -145,6 +213,66 @@ function filterAiProfileRowsForTrustedSeatScope(deps, rows, trustedSeatScope) {
         return rows;
     return rows.filter((row) => aiProfileMatchesTrustedSeatScope(deps, row, trustedSeatScope));
 }
+function normalizeAiProfileIdentityValue(value) {
+    return String(value || '').trim().toLowerCase();
+}
+function latestAiProfileActivityValue(row) {
+    return normalizeNullableIsoString(row.last_active_at)
+        ?? normalizeNullableIsoString(row.updated_at)
+        ?? normalizeNullableIsoString(row.created_at)
+        ?? '';
+}
+function rankNullableIdentityMatch(existingValue, incomingValue) {
+    const existing = normalizeAiProfileIdentityValue(existingValue);
+    if (incomingValue) {
+        if (existing === incomingValue)
+            return 2;
+        if (!existing)
+            return 1;
+        return 0;
+    }
+    return existing ? 0 : 1;
+}
+function selectAiProfileIdentityMatch(deps, rows, input, trustedSeatScope) {
+    const scopedRows = filterAiProfileRowsForTrustedSeatScope(deps, rows, trustedSeatScope);
+    const incomingProvider = normalizeAiProfileIdentityValue(input.provider) || null;
+    const incomingModel = normalizeAiProfileIdentityValue(input.model) || null;
+    const incomingSurfaceType = input.surfaceTypeProvided
+        ? normalizeAiProfileIdentityValue(input.surfaceType) || null
+        : null;
+    const ranked = scopedRows
+        .map((row) => {
+        const providerRank = rankNullableIdentityMatch(row.provider, incomingProvider);
+        const surfaceRank = input.surfaceTypeProvided
+            ? rankNullableIdentityMatch(row.surface_type, incomingSurfaceType)
+            : 0;
+        const modelRank = incomingModel && normalizeAiProfileIdentityValue(row.model) === incomingModel ? 1 : 0;
+        return {
+            row,
+            providerRank,
+            surfaceRank,
+            modelRank,
+            activity: latestAiProfileActivityValue(row),
+        };
+    })
+        .filter((entry) => Boolean(entry))
+        .sort((left, right) => {
+        if (right.providerRank !== left.providerRank)
+            return right.providerRank - left.providerRank;
+        if (right.surfaceRank !== left.surfaceRank)
+            return right.surfaceRank - left.surfaceRank;
+        if (right.modelRank !== left.modelRank)
+            return right.modelRank - left.modelRank;
+        const activityDelta = right.activity.localeCompare(left.activity);
+        if (activityDelta !== 0)
+            return activityDelta;
+        return String(left.row.id || '').localeCompare(String(right.row.id || ''));
+    });
+    return {
+        row: ranked[0]?.row,
+        matchCount: ranked.length,
+    };
+}
 function requiresCloudSeatReservation(existing, nextSeatScope) {
     if (nextSeatScope !== 'cloud_metered')
         return false;
@@ -194,6 +322,12 @@ function inferAiProfileMetadataDefaults(name, surfaceType) {
                 role: 'Coding Agent',
                 ...inferredProviderModel
             };
+        case 'cli':
+            return {
+                description: `${name} CLI coding agent connected through MCP.`,
+                role: 'CLI Coding Agent',
+                ...inferredProviderModel
+            };
         case 'chat_app':
             return {
                 description: `${name} conversational AI connected through Taskforce.`,
@@ -206,12 +340,6 @@ function inferAiProfileMetadataDefaults(name, surfaceType) {
                 role: 'Coding Assistant',
                 ...inferredProviderModel
             };
-        case 'other':
-            return {
-                description: `${name} AI profile connected through Taskforce.`,
-                role: 'AI Assistant',
-                ...inferredProviderModel
-            };
         default:
             return {};
     }
@@ -227,7 +355,9 @@ function resolveOptionalProfileField(inputValue, existingValue, fallbackValue) {
 }
 function resolveAiProfileMetadataFields(deps, input, existing) {
     const surfaceTypeInput = normalizeAiProfileSurfaceTypeInput(deps, input.surfaceType);
+    const manuallyOverridden = hasManualSurfaceTypeOverride(existing);
     const effectiveSurfaceType = surfaceTypeInput === undefined
+        || manuallyOverridden
         ? existing?.surfaceType ?? null
         : surfaceTypeInput;
     const inferredDefaults = inferAiProfileMetadataDefaults(input.name, effectiveSurfaceType);
@@ -237,7 +367,7 @@ function resolveAiProfileMetadataFields(deps, input, existing) {
         provider: resolveOptionalProfileField(input.provider, existing?.provider, inferredDefaults.provider) ?? null,
         model: resolveOptionalProfileField(input.model, existing?.model, inferredDefaults.model) ?? null,
         surfaceType: effectiveSurfaceType,
-        surfaceTypeProvided: surfaceTypeInput !== undefined,
+        surfaceTypeProvided: surfaceTypeInput !== undefined && !manuallyOverridden,
     };
 }
 function applyAiProfileMetadataDefaults(record) {
@@ -250,7 +380,167 @@ function applyAiProfileMetadataDefaults(record) {
         model: resolveOptionalProfileField(undefined, record.model, inferredDefaults.model) ?? null,
     };
 }
+function backfillMissingAiProfileAvatarFromDuplicate(deps, row) {
+    const id = String(row.id || '').trim();
+    const workspaceId = String(row.workspace_id || '').trim();
+    const name = String(row.name || '').trim();
+    const username = String(row.username || '').trim();
+    if (!id || !workspaceId || (!name && !username))
+        return;
+    const currentAvatarUrl = normalizeAiProfileAvatarUrl(row.avatar_url);
+    const currentAvatarSourceUrl = normalizeAiProfileAvatarUrl(row.avatar_source_url);
+    if (hasAiProfileAvatarState(currentAvatarUrl, currentAvatarSourceUrl))
+        return;
+    const currentRevision = normalizeAiProfileAvatarRevision(row.avatar_revision);
+    const donor = deps.db.prepare(`
+        SELECT avatar_url, avatar_source_url, avatar_revision, avatar_updated_at, updated_at
+        FROM ai_profiles
+        WHERE tenant_id = ?
+          AND workspace_id = ?
+          AND id <> ?
+          AND archived_at IS NULL
+          AND (
+                (? <> '' AND LOWER(name) = LOWER(?))
+                OR (? <> '' AND LOWER(username) = LOWER(?))
+          )
+          AND (
+                (avatar_url IS NOT NULL AND TRIM(avatar_url) <> '')
+                OR (avatar_source_url IS NOT NULL AND TRIM(avatar_source_url) <> '')
+          )
+        ORDER BY COALESCE(avatar_revision, 0) DESC,
+                 COALESCE(avatar_updated_at, updated_at) DESC,
+                 id ASC
+        LIMIT 1
+    `).get(deps.tenantId, workspaceId, id, name, name, username, username);
+    if (!donor)
+        return;
+    const donorRevision = normalizeAiProfileAvatarRevision(donor.avatar_revision);
+    if (donorRevision < currentRevision)
+        return;
+    const donorAvatarUrl = normalizeAiProfileAvatarUrl(donor.avatar_url);
+    const donorAvatarSourceUrl = normalizeAiProfileAvatarUrl(donor.avatar_source_url);
+    if (!hasAiProfileAvatarState(donorAvatarUrl, donorAvatarSourceUrl))
+        return;
+    const nextRevision = Math.max(currentRevision, donorRevision, 1);
+    const nextAvatarUpdatedAt = normalizeNullableIsoString(donor.avatar_updated_at)
+        ?? normalizeNullableIsoString(donor.updated_at)
+        ?? new Date().toISOString();
+    deps.db.prepare(`
+        UPDATE ai_profiles
+        SET avatar_url = ?,
+            avatar_source_url = ?,
+            avatar_revision = ?,
+            avatar_updated_at = ?,
+            updated_at = ?
+        WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+    `).run(donorAvatarUrl, donorAvatarSourceUrl, nextRevision, nextAvatarUpdatedAt, nextAvatarUpdatedAt, deps.tenantId, workspaceId, id);
+    row.avatar_url = donorAvatarUrl;
+    row.avatar_source_url = donorAvatarSourceUrl;
+    row.avatar_revision = nextRevision;
+    row.avatar_updated_at = nextAvatarUpdatedAt;
+    row.updated_at = nextAvatarUpdatedAt;
+}
+function backfillMissingAiProfileAvatarFromAssetIndex(deps, row) {
+    const id = String(row.id || '').trim();
+    const workspaceId = String(row.workspace_id || '').trim();
+    if (!id || !workspaceId)
+        return;
+    const currentAvatarUrl = normalizeAiProfileAvatarUrl(row.avatar_url);
+    const currentAvatarSourceUrl = normalizeAiProfileAvatarUrl(row.avatar_source_url);
+    if (hasAiProfileAvatarState(currentAvatarUrl, currentAvatarSourceUrl))
+        return;
+    if (normalizeAiProfileAvatarRevision(row.avatar_revision) > 0)
+        return;
+    if (normalizeNullableIsoString(row.avatar_updated_at))
+        return;
+    const avatarPrefix = `workspaces/${workspaceId}/assets/images/ai-profiles/${id}/avatar/`;
+    try {
+        const latestCropped = deps.db.prepare(`
+            SELECT storage_key, updated_at, created_at
+            FROM workspace_assets
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND deleted_at IS NULL
+              AND storage_key LIKE ?
+              AND (
+                    LOWER(original_filename) LIKE 'cropped-%'
+                    OR LOWER(logical_name) = 'ai profile avatar display'
+                    OR LOWER(storage_key) LIKE '%/display.webp'
+                    OR LOWER(storage_key) LIKE '%/display.gif'
+                    OR LOWER(storage_key) LIKE '%/display.png'
+                    OR LOWER(storage_key) LIKE '%/display.jpg'
+                    OR LOWER(storage_key) LIKE '%/display.jpeg'
+                    OR LOWER(original_filename) = 'avatar.webp'
+                    OR LOWER(original_filename) = 'avatar.png'
+                    OR LOWER(original_filename) = 'avatar.jpg'
+                    OR LOWER(original_filename) = 'avatar.jpeg'
+              )
+            ORDER BY COALESCE(updated_at, created_at) DESC, storage_key DESC
+            LIMIT 1
+        `).get(deps.tenantId, workspaceId, `${avatarPrefix}%`);
+        if (!latestCropped)
+            return;
+        const latestSource = deps.db.prepare(`
+            SELECT storage_key, updated_at, created_at
+            FROM workspace_assets
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND deleted_at IS NULL
+              AND storage_key LIKE ?
+              AND (
+                    LOWER(original_filename) LIKE 'source-%'
+                    OR LOWER(logical_name) = 'ai profile avatar source'
+                    OR LOWER(storage_key) LIKE '%/source.webp'
+                    OR LOWER(storage_key) LIKE '%/source.gif'
+                    OR LOWER(storage_key) LIKE '%/source.png'
+                    OR LOWER(storage_key) LIKE '%/source.jpg'
+                    OR LOWER(storage_key) LIKE '%/source.jpeg'
+              )
+            ORDER BY COALESCE(updated_at, created_at) DESC, storage_key DESC
+            LIMIT 1
+        `).get(deps.tenantId, workspaceId, `${avatarPrefix}%`);
+        const avatarStorageKey = String(latestCropped.storage_key || '').trim();
+        if (!avatarStorageKey)
+            return;
+        const sourceStorageKey = String(latestSource?.storage_key || '').trim();
+        const avatarUrl = `/api/taskforce/context/${encodeURIComponent(avatarStorageKey)}`;
+        const avatarSourceUrl = sourceStorageKey
+            ? `/api/taskforce/context/${encodeURIComponent(sourceStorageKey)}`
+            : null;
+        const repairedAt = normalizeNullableIsoString(latestCropped.updated_at)
+            ?? normalizeNullableIsoString(latestCropped.created_at)
+            ?? new Date().toISOString();
+        deps.db.prepare(`
+            UPDATE ai_profiles
+            SET avatar_url = ?,
+                avatar_source_url = ?,
+                avatar_revision = 1,
+                avatar_updated_at = ?,
+                updated_at = CASE
+                    WHEN updated_at IS NULL OR TRIM(updated_at) = '' OR updated_at < ? THEN ?
+                    ELSE updated_at
+                END
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+              AND (avatar_url IS NULL OR TRIM(avatar_url) = '')
+              AND (avatar_source_url IS NULL OR TRIM(avatar_source_url) = '')
+              AND COALESCE(avatar_revision, 0) = 0
+              AND (avatar_updated_at IS NULL OR TRIM(avatar_updated_at) = '')
+        `).run(avatarUrl, avatarSourceUrl, repairedAt, repairedAt, repairedAt, deps.tenantId, workspaceId, id);
+        row.avatar_url = avatarUrl;
+        row.avatar_source_url = avatarSourceUrl;
+        row.avatar_revision = 1;
+        row.avatar_updated_at = repairedAt;
+        if (!normalizeNullableIsoString(row.updated_at) || String(row.updated_at) < repairedAt) {
+            row.updated_at = repairedAt;
+        }
+    }
+    catch {
+        // Older or mocked stores may not have workspace_assets available.
+    }
+}
 function hydrateAiProfileRecord(deps, row, diagnostics) {
+    backfillMissingAiProfileAvatarFromDuplicate(deps, row);
+    backfillMissingAiProfileAvatarFromAssetIndex(deps, row);
     const record = deps.aiProfileRowToRecord(row);
     const hydrated = applyAiProfileMetadataDefaults(record);
     const metadataChanged = record.description !== hydrated.description
@@ -286,6 +576,8 @@ export function listAiProfilesService(deps, workspaceId, options) {
             color,
             avatar_url,
             avatar_source_url,
+            avatar_revision,
+            avatar_updated_at,
             description,
             role,
             provider,
@@ -358,6 +650,9 @@ export function upsertAiProfileForSyncService(deps, profile) {
     const existingProfile = existingRow ? deps.aiProfileRowToRecord(existingRow) : null;
     const incomingAvatarUrlProvided = Object.prototype.hasOwnProperty.call(profile, 'avatarUrl');
     const incomingAvatarSourceUrlProvided = Object.prototype.hasOwnProperty.call(profile, 'avatarSourceUrl');
+    const incomingAvatarRevisionProvided = Object.prototype.hasOwnProperty.call(profile, 'avatarRevision');
+    const incomingAvatarRevision = normalizeAiProfileAvatarRevision(profile.avatarRevision);
+    const incomingAvatarUpdatedAt = normalizeNullableIsoString(profile.avatarUpdatedAt);
     const existingCreatedAt = existingRow
         ? String(existingRow.created_at || existingRow.updated_at || '').trim()
         : '';
@@ -386,6 +681,8 @@ export function upsertAiProfileForSyncService(deps, profile) {
             updatedAt: existingUpdatedAt,
         })
         : null;
+    const existingAvatarRevision = normalizeAiProfileAvatarRevision(existingRow?.avatar_revision);
+    const existingAvatarUpdatedAt = normalizeNullableIsoString(existingRow?.avatar_updated_at);
     const metadataComparison = compareIsoStrings(normalizedUpdatedAt, existingUpdatedAt);
     const incomingMetadataWins = !existingRow || metadataComparison > 0;
     const lifecycleComparison = compareIsoStrings(normalizedRosterStateUpdatedAt, existingRosterStateUpdatedAt);
@@ -447,13 +744,47 @@ export function upsertAiProfileForSyncService(deps, profile) {
     const mergedUsername = metadataSourceProfile?.username ?? deps.normalizeAiProfileUsername(profile.username, profile.name);
     const mergedIcon = metadataSourceProfile?.icon ?? deps.normalizeAiProfileIcon(profile.icon);
     const mergedColor = metadataSourceProfile?.color ?? deps.normalizeAiProfileColor(profile.color);
-    const incomingAvatarFieldsWin = incomingMetadataWins || metadataComparison === 0;
-    const mergedAvatarUrl = incomingAvatarUrlProvided && incomingAvatarFieldsWin
-        ? normalizeAiProfileAvatarUrl(profile.avatarUrl)
-        : normalizeAiProfileAvatarUrl(existingProfile?.avatarUrl);
-    const mergedAvatarSourceUrl = incomingAvatarSourceUrlProvided && incomingAvatarFieldsWin
-        ? normalizeAiProfileAvatarUrl(profile.avatarSourceUrl)
-        : normalizeAiProfileAvatarUrl(existingProfile?.avatarSourceUrl);
+    const existingAvatarUrl = normalizeAiProfileAvatarUrl(existingProfile?.avatarUrl);
+    const existingAvatarSourceUrl = normalizeAiProfileAvatarUrl(existingProfile?.avatarSourceUrl);
+    const incomingAvatarUrl = incomingAvatarUrlProvided ? normalizeAiProfileAvatarUrl(profile.avatarUrl) : null;
+    const incomingAvatarSourceUrl = incomingAvatarSourceUrlProvided ? normalizeAiProfileAvatarUrl(profile.avatarSourceUrl) : null;
+    const incomingHasAvatarState = hasAiProfileAvatarState(incomingAvatarUrl, incomingAvatarSourceUrl);
+    const existingHasAvatarState = hasAiProfileAvatarState(existingAvatarUrl, existingAvatarSourceUrl);
+    let mergedAvatarUrl = existingAvatarUrl;
+    let mergedAvatarSourceUrl = existingAvatarSourceUrl;
+    let mergedAvatarRevision = existingAvatarRevision;
+    let mergedAvatarUpdatedAt = existingAvatarUpdatedAt;
+    if (!existingRow) {
+        mergedAvatarUrl = incomingAvatarUrlProvided ? incomingAvatarUrl : null;
+        mergedAvatarSourceUrl = incomingAvatarSourceUrlProvided ? incomingAvatarSourceUrl : null;
+        mergedAvatarRevision = incomingAvatarRevisionProvided ? incomingAvatarRevision : (incomingHasAvatarState ? 1 : 0);
+        mergedAvatarUpdatedAt = incomingAvatarUpdatedAt ?? (incomingHasAvatarState ? normalizedUpdatedAt : null);
+    }
+    else if (incomingAvatarRevisionProvided) {
+        if (incomingAvatarRevision > existingAvatarRevision) {
+            const incomingClearsAvatar = !incomingHasAvatarState && existingHasAvatarState;
+            const clearHasAvatarTimestamp = Boolean(incomingAvatarUpdatedAt);
+            if (!incomingClearsAvatar || clearHasAvatarTimestamp) {
+                mergedAvatarUrl = incomingAvatarUrlProvided ? incomingAvatarUrl : existingAvatarUrl;
+                mergedAvatarSourceUrl = incomingAvatarSourceUrlProvided ? incomingAvatarSourceUrl : existingAvatarSourceUrl;
+                mergedAvatarRevision = incomingAvatarRevision;
+                mergedAvatarUpdatedAt = incomingAvatarUpdatedAt ?? normalizedUpdatedAt;
+            }
+        }
+        else if (incomingAvatarRevision === existingAvatarRevision) {
+            if (!existingHasAvatarState && incomingHasAvatarState) {
+                mergedAvatarUrl = incomingAvatarUrl;
+                mergedAvatarSourceUrl = incomingAvatarSourceUrl;
+                mergedAvatarUpdatedAt = incomingAvatarUpdatedAt ?? existingAvatarUpdatedAt ?? normalizedUpdatedAt;
+            }
+        }
+    }
+    else if (!existingHasAvatarState && incomingHasAvatarState) {
+        mergedAvatarUrl = incomingAvatarUrl;
+        mergedAvatarSourceUrl = incomingAvatarSourceUrl;
+        mergedAvatarRevision = Math.max(existingAvatarRevision, 1);
+        mergedAvatarUpdatedAt = existingAvatarUpdatedAt ?? normalizedUpdatedAt;
+    }
     const mergedProviderMetadata = incomingMetadataWins
         ? (profile.providerMetadata && typeof profile.providerMetadata === 'object' && !Array.isArray(profile.providerMetadata)
             ? JSON.stringify(profile.providerMetadata)
@@ -474,10 +805,11 @@ export function upsertAiProfileForSyncService(deps, profile) {
     deps.db.prepare(`
         INSERT INTO ai_profiles (
             id, tenant_id, workspace_id, profile_token, name, username, icon, color,
-            avatar_url, avatar_source_url, description, role, provider, model, surface_type, seat_scope, provider_metadata_json,
+            avatar_url, avatar_source_url, avatar_revision, avatar_updated_at,
+            description, role, provider, model, surface_type, seat_scope, provider_metadata_json,
             archived_at, archived_by, archived_reason, merged_into_profile_id,
             roster_state_updated_at, created_at, updated_at, last_active_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         ON CONFLICT(id) DO UPDATE SET
             workspace_id = excluded.workspace_id,
             profile_token = excluded.profile_token,
@@ -487,6 +819,8 @@ export function upsertAiProfileForSyncService(deps, profile) {
             color = excluded.color,
             avatar_url = excluded.avatar_url,
             avatar_source_url = excluded.avatar_source_url,
+            avatar_revision = excluded.avatar_revision,
+            avatar_updated_at = excluded.avatar_updated_at,
             description = excluded.description,
             role = excluded.role,
             provider = excluded.provider,
@@ -502,7 +836,7 @@ export function upsertAiProfileForSyncService(deps, profile) {
             created_at = excluded.created_at,
             updated_at = excluded.updated_at,
             last_active_at = excluded.last_active_at
-    `).run(profileId, deps.tenantId, normalizedWorkspaceId, mergedProfileToken, mergedName, mergedUsername, mergedIcon, mergedColor, mergedAvatarUrl, mergedAvatarSourceUrl, resolvedMetadata.description, resolvedMetadata.role, resolvedMetadata.provider, resolvedMetadata.model, resolvedMetadata.surfaceType, resolvedSeatScope.seatScope, mergedProviderMetadata, mergedArchivedAt, mergedArchivedBy, mergedArchivedReason, mergedMergedIntoProfileId, mergedRosterStateUpdatedAt, mergedCreatedAt, mergedUpdatedAt, mergedLastActiveAt);
+    `).run(profileId, deps.tenantId, normalizedWorkspaceId, mergedProfileToken, mergedName, mergedUsername, mergedIcon, mergedColor, mergedAvatarUrl, mergedAvatarSourceUrl, mergedAvatarRevision, mergedAvatarUpdatedAt, resolvedMetadata.description, resolvedMetadata.role, resolvedMetadata.provider, resolvedMetadata.model, resolvedMetadata.surfaceType, resolvedSeatScope.seatScope, mergedProviderMetadata, mergedArchivedAt, mergedArchivedBy, mergedArchivedReason, mergedMergedIntoProfileId, mergedRosterStateUpdatedAt, mergedCreatedAt, mergedUpdatedAt, mergedLastActiveAt);
     const refreshed = deps.db.prepare(`
         SELECT *
         FROM ai_profiles
@@ -534,6 +868,17 @@ export function mergeAiProfilesService(deps, input) {
         throw deps.createRuleError(`Profile ${mergeId} not found`, 404, 'MERGE_PROFILES_MERGE_NOT_FOUND');
     const keepRecord = deps.aiProfileRowToRecord(keepProfile);
     const mergeRecord = deps.aiProfileRowToRecord(mergeProfile);
+    const keepSeatScope = keepRecord.seatScope ?? null;
+    const mergeSeatScope = mergeRecord.seatScope ?? null;
+    if (keepSeatScope && mergeSeatScope && keepSeatScope !== mergeSeatScope) {
+        throw deps.createRuleError('Local and cloud AI profiles are separate registrations and cannot be merged. Retire one from the roster instead.', 409, 'AI_PROFILE_SEAT_SCOPE_MISMATCH', {
+            workspaceId: normalizedWorkspaceId,
+            keepId,
+            mergeId,
+            keepSeatScope,
+            mergeSeatScope,
+        });
+    }
     const mergedSeatScope = resolveAiProfileSeatScope(deps, mergeRecord.seatScope, keepRecord);
     const mergedAt = new Date().toISOString();
     const doMerge = deps.db.transaction(() => {
@@ -598,14 +943,41 @@ export function updateAiProfileAvatarService(deps, input) {
     if (typeof input.avatarSourceUrl === 'string' && input.avatarSourceUrl.trim().length > 0 && !avatarSourceUrl) {
         throw deps.createRuleError('avatarSourceUrl must be a Taskforce context URL', 400, 'AI_PROFILE_AVATAR_SOURCE_URL_INVALID');
     }
+    const currentRevision = normalizeAiProfileAvatarRevision(existing.avatar_revision);
+    const nextRevision = currentRevision + 1;
     const updatedAt = new Date().toISOString();
     deps.db.prepare(`
         UPDATE ai_profiles
         SET avatar_url = ?,
             avatar_source_url = ?,
+            avatar_revision = ?,
+            avatar_updated_at = ?,
             updated_at = ?
         WHERE tenant_id = ? AND workspace_id = ? AND id = ?
-    `).run(avatarUrl, avatarSourceUrl, updatedAt, deps.tenantId, normalizedWorkspaceId, profileId);
+    `).run(avatarUrl, avatarSourceUrl, nextRevision, updatedAt, updatedAt, deps.tenantId, normalizedWorkspaceId, profileId);
+    if (avatarUrl) {
+        deps.db.prepare(`
+            UPDATE ai_profiles
+            SET avatar_url = ?,
+                avatar_source_url = ?,
+                avatar_revision = CASE
+                    WHEN COALESCE(avatar_revision, 0) < ? THEN ?
+                    ELSE COALESCE(avatar_revision, 0)
+                END,
+                avatar_updated_at = ?,
+                updated_at = ?
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND id <> ?
+              AND archived_at IS NULL
+              AND (
+                    LOWER(name) = LOWER(?)
+                    OR LOWER(username) = LOWER(?)
+              )
+              AND (avatar_url IS NULL OR TRIM(avatar_url) = '')
+              AND (avatar_source_url IS NULL OR TRIM(avatar_source_url) = '')
+        `).run(avatarUrl, avatarSourceUrl, nextRevision, nextRevision, updatedAt, updatedAt, deps.tenantId, normalizedWorkspaceId, profileId, String(existing.name || '').trim(), deps.normalizeAiProfileUsername(existing.username, String(existing.name || '').trim()));
+    }
     const refreshed = deps.db.prepare(`
         SELECT *
         FROM ai_profiles
@@ -617,6 +989,46 @@ export function updateAiProfileAvatarService(deps, input) {
     }
     return hydrateAiProfileRecord(deps, refreshed);
 }
+export function updateAiProfileSurfaceTypeService(deps, input) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(input.workspaceId);
+    const profileId = String(input.profileId || '').trim();
+    if (!profileId)
+        throw deps.createRuleError('profileId is required', 400, 'AI_PROFILE_ID_REQUIRED');
+    const surfaceType = normalizeAiProfileSurfaceTypeInput(deps, input.surfaceType);
+    if (surfaceType === undefined) {
+        throw deps.createRuleError('surfaceType is required', 400, 'AI_PROFILE_SURFACE_TYPE_REQUIRED');
+    }
+    const existing = deps.db.prepare(`
+        SELECT *
+        FROM ai_profiles
+        WHERE tenant_id = ? AND workspace_id = ? AND id = ? AND archived_at IS NULL
+        LIMIT 1
+    `).get(deps.tenantId, normalizedWorkspaceId, profileId);
+    if (!existing) {
+        throw deps.createRuleError(`Profile ${profileId} not found`, 404, 'AI_PROFILE_NOT_FOUND');
+    }
+    const providerMetadataJson = surfaceType === null
+        ? clearManualSurfaceTypeOverride(existing)
+        : markManualSurfaceTypeOverride(existing);
+    const updatedAt = new Date().toISOString();
+    deps.db.prepare(`
+        UPDATE ai_profiles
+        SET surface_type = ?,
+            provider_metadata_json = ?,
+            updated_at = ?
+        WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+    `).run(surfaceType, providerMetadataJson, updatedAt, deps.tenantId, normalizedWorkspaceId, profileId);
+    const refreshed = deps.db.prepare(`
+        SELECT *
+        FROM ai_profiles
+        WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+        LIMIT 1
+    `).get(deps.tenantId, normalizedWorkspaceId, profileId);
+    if (!refreshed) {
+        throw deps.createRuleError('Failed to update AI profile category', 500, 'AI_PROFILE_SURFACE_TYPE_UPDATE_FAILED');
+    }
+    return hydrateAiProfileRecord(deps, refreshed);
+}
 export function archiveAiProfileService(deps, input) {
     const normalizedWorkspaceId = deps.normalizeWorkspaceId(input.workspaceId);
     const profileId = String(input.profileId || '').trim();
@@ -697,12 +1109,7 @@ export function resolveAiProfileService(deps, input, options) {
                 ORDER BY COALESCE(last_active_at, updated_at, created_at) DESC, id ASC
             `).all(deps.tenantId, normalizedWorkspaceId, profileToken);
             const archivedRow = findFirstAiProfileRowForTrustedSeatScope(deps, archivedRows, trustedSeatScope);
-            if (!archivedRow) {
-                if (existingRows.length === 0 && archivedRows.length === 0) {
-                    throw deps.createRuleError('AI profile token is invalid for this workspace', 404, 'AI_PROFILE_NOT_FOUND');
-                }
-            }
-            else {
+            if (archivedRow) {
                 const existingProfile = deps.aiProfileRowToRecord(archivedRow);
                 const nextName = name;
                 const nextUsername = deps.normalizeAiProfileUsername(undefined, nextName);
@@ -769,6 +1176,9 @@ export function resolveAiProfileService(deps, input, options) {
                     profile: hydrateAiProfileRecord(deps, refreshed)
                 };
             }
+            // Treat token misses as recoverable when the caller also supplied profile
+            // identity metadata; the name/seat-scope resolver below can bind stale
+            // reconnects without minting duplicates.
         }
         else {
             const existingProfile = deps.aiProfileRowToRecord(existingRow);
@@ -833,6 +1243,21 @@ export function resolveAiProfileService(deps, input, options) {
             };
         }
     }
+    const identityDescription = normalizeOptionalProfileField(input.description);
+    const identityRole = normalizeOptionalProfileField(input.role);
+    const inferredIdentity = inferAiProfileProviderModelDefaults(name);
+    const identityProvider = normalizeOptionalProfileField(input.provider)
+        ?? normalizeOptionalProfileField(inferredIdentity.provider);
+    const identityModel = normalizeOptionalProfileField(input.model)
+        ?? normalizeOptionalProfileField(inferredIdentity.model);
+    const identityMetadata = resolveAiProfileMetadataFields(deps, {
+        name,
+        description: identityDescription,
+        role: identityRole,
+        provider: identityProvider,
+        model: identityModel,
+        surfaceType: input.surfaceType,
+    }, null);
     const exactMatches = deps.db.prepare(`
         SELECT *
         FROM ai_profiles
@@ -845,9 +1270,9 @@ export function resolveAiProfileService(deps, input, options) {
           )
         ORDER BY COALESCE(last_active_at, updated_at, created_at) DESC, id ASC
     `).all(deps.tenantId, normalizedWorkspaceId, name, deps.normalizeAiProfileUsername(undefined, name));
-    const scopedExactMatches = filterAiProfileRowsForTrustedSeatScope(deps, exactMatches, trustedSeatScope);
-    if (scopedExactMatches.length > 0) {
-        const canonicalId = String(scopedExactMatches[0].id || '').trim();
+    const exactMatch = selectAiProfileIdentityMatch(deps, exactMatches, identityMetadata, trustedSeatScope);
+    if (exactMatch.row) {
+        const canonicalId = String(exactMatch.row.id || '').trim();
         const nextName = name;
         const nextUsername = deps.normalizeAiProfileUsername(undefined, nextName);
         const nextIcon = deps.normalizeAiProfileIcon(input.icon);
@@ -856,7 +1281,7 @@ export function resolveAiProfileService(deps, input, options) {
         const nextRole = normalizeOptionalProfileField(input.role);
         const nextProvider = normalizeOptionalProfileField(input.provider);
         const nextModel = normalizeOptionalProfileField(input.model);
-        const existingProfile = deps.aiProfileRowToRecord(scopedExactMatches[0]);
+        const existingProfile = deps.aiProfileRowToRecord(exactMatch.row);
         const resolvedMetadata = resolveAiProfileMetadataFields(deps, {
             name: nextName,
             description: nextDescription,
@@ -903,7 +1328,7 @@ export function resolveAiProfileService(deps, input, options) {
         return {
             created: false,
             profile: hydrateAiProfileRecord(deps, reused),
-            ...(scopedExactMatches.length > 1 ? {
+            ...(exactMatch.matchCount > 1 ? {
                 duplicateWarning: {
                     existingProfileId: canonicalId,
                     message: `Multiple profiles matched "${name}". Reused ${canonicalId}; merge the remaining duplicates.`
@@ -923,9 +1348,9 @@ export function resolveAiProfileService(deps, input, options) {
           )
         ORDER BY COALESCE(last_active_at, updated_at, created_at) DESC, id ASC
     `).all(deps.tenantId, normalizedWorkspaceId, name, deps.normalizeAiProfileUsername(undefined, name));
-    const scopedArchivedMatches = filterAiProfileRowsForTrustedSeatScope(deps, archivedMatches, trustedSeatScope);
-    if (scopedArchivedMatches.length > 0) {
-        const canonicalId = String(scopedArchivedMatches[0].id || '').trim();
+    const archivedMatch = selectAiProfileIdentityMatch(deps, archivedMatches, identityMetadata, trustedSeatScope);
+    if (archivedMatch.row) {
+        const canonicalId = String(archivedMatch.row.id || '').trim();
         const nextName = name;
         const nextUsername = deps.normalizeAiProfileUsername(undefined, nextName);
         const nextIcon = deps.normalizeAiProfileIcon(input.icon);
@@ -934,7 +1359,7 @@ export function resolveAiProfileService(deps, input, options) {
         const nextRole = normalizeOptionalProfileField(input.role);
         const nextProvider = normalizeOptionalProfileField(input.provider);
         const nextModel = normalizeOptionalProfileField(input.model);
-        const existingProfile = deps.aiProfileRowToRecord(scopedArchivedMatches[0]);
+        const existingProfile = deps.aiProfileRowToRecord(archivedMatch.row);
         const resolvedMetadata = resolveAiProfileMetadataFields(deps, {
             name: nextName,
             description: nextDescription,