@taskforcehq/taskforce 0.3.169 → 0.3.300

package/dist/config/clientDeployment.js

@@ -0,0 +1,13 @@
+import { resolveDeploymentConfig } from './deployment.js';
+export function resolveClientDeploymentConfig(env) {
+    return resolveDeploymentConfig({
+        TASKFORCE_CLOUD_ENVIRONMENT: typeof __TASKFORCE_CLOUD_ENVIRONMENT__ === 'string'
+            ? __TASKFORCE_CLOUD_ENVIRONMENT__
+            : '',
+        VITE_TASKFORCE_BASE_URL: env.VITE_TASKFORCE_BASE_URL,
+        VITE_TASKFORCE_API_BASE_URL: env.VITE_TASKFORCE_API_BASE_URL,
+        VITE_TASKFORCE_CLOUD_AUTH_BASE_URL: env.VITE_TASKFORCE_CLOUD_AUTH_BASE_URL,
+        VITE_TASKFORCE_CLOUD_MCP_BASE_URL: env.VITE_TASKFORCE_CLOUD_MCP_BASE_URL,
+        VITE_TASKFORCE_WS_BASE_URL: env.VITE_TASKFORCE_WS_BASE_URL
+    });
+}

package/dist/config/cloudEnvironment.d.ts

@@ -0,0 +1,15 @@
+export type TaskforceCloudEnvironment = 'production' | 'staging' | 'performance';
+export interface TaskforceCloudEnvironmentConfig {
+    appBaseUrl: string;
+    mcpBaseUrl: string;
+    label: string;
+    themeToken: TaskforceCloudEnvironment;
+}
+export declare const TASKFORCE_CLOUD_ENVIRONMENT_ORDER: TaskforceCloudEnvironment[];
+export declare const TASKFORCE_CLOUD_ENVIRONMENTS: Record<TaskforceCloudEnvironment, TaskforceCloudEnvironmentConfig>;
+export declare function parseTaskforceCloudEnvironment(raw: unknown): TaskforceCloudEnvironment | null;
+export declare function normalizeTaskforceCloudEnvironment(raw: string | undefined | null): TaskforceCloudEnvironment;
+export declare function getTaskforceCloudEnvironmentConfig(raw: unknown): TaskforceCloudEnvironmentConfig;
+export declare function resolveTaskforceCloudEnvironmentFromHostname(raw: string | undefined | null): TaskforceCloudEnvironment | null;
+export declare function resolveTaskforceCloudEnvironmentFromBaseUrl(raw: string | undefined | null): TaskforceCloudEnvironment | null;
+export declare function resolveTaskforceMcpBaseUrlFromBaseUrl(raw: string | undefined | null): string | null;

package/dist/config/cloudEnvironment.js

@@ -0,0 +1,60 @@
+export const TASKFORCE_CLOUD_ENVIRONMENT_ORDER = ['production', 'staging', 'performance'];
+export const TASKFORCE_CLOUD_ENVIRONMENTS = {
+    production: {
+        appBaseUrl: 'https://app.taskforcehq.ai',
+        mcpBaseUrl: 'https://mcp.taskforcehq.ai',
+        label: 'Production',
+        themeToken: 'production'
+    },
+    staging: {
+        appBaseUrl: 'https://staging-app.taskforcehq.ai',
+        mcpBaseUrl: 'https://staging-mcp.taskforcehq.ai',
+        label: 'Staging',
+        themeToken: 'staging'
+    },
+    performance: {
+        appBaseUrl: 'https://performance-app.taskforcehq.ai',
+        mcpBaseUrl: 'https://performance-mcp.taskforcehq.ai',
+        label: 'Performance',
+        themeToken: 'performance'
+    }
+};
+export function parseTaskforceCloudEnvironment(raw) {
+    const value = String(raw || '').trim().toLowerCase();
+    if (value === 'production' || value === 'staging' || value === 'performance')
+        return value;
+    return null;
+}
+export function normalizeTaskforceCloudEnvironment(raw) {
+    return parseTaskforceCloudEnvironment(raw) || 'production';
+}
+export function getTaskforceCloudEnvironmentConfig(raw) {
+    return TASKFORCE_CLOUD_ENVIRONMENTS[normalizeTaskforceCloudEnvironment(String(raw || ''))];
+}
+export function resolveTaskforceCloudEnvironmentFromHostname(raw) {
+    const hostname = String(raw || '').trim().toLowerCase();
+    if (!hostname)
+        return null;
+    for (const [environment, config] of Object.entries(TASKFORCE_CLOUD_ENVIRONMENTS)) {
+        if (new URL(config.appBaseUrl).hostname.toLowerCase() === hostname
+            || new URL(config.mcpBaseUrl).hostname.toLowerCase() === hostname) {
+            return environment;
+        }
+    }
+    return null;
+}
+export function resolveTaskforceCloudEnvironmentFromBaseUrl(raw) {
+    const value = String(raw || '').trim();
+    if (!value)
+        return null;
+    try {
+        return resolveTaskforceCloudEnvironmentFromHostname(new URL(value).hostname);
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveTaskforceMcpBaseUrlFromBaseUrl(raw) {
+    const environment = resolveTaskforceCloudEnvironmentFromBaseUrl(raw);
+    return environment ? TASKFORCE_CLOUD_ENVIRONMENTS[environment].mcpBaseUrl : null;
+}

package/dist/config/deployment.d.ts

@@ -0,0 +1,20 @@
+import { type TaskforceCloudEnvironment } from './cloudEnvironment.js';
+import { type CompatWarningHandler, type EnvLike } from '../compat/deploymentCompat.js';
+export type RuntimeMode = 'local' | 'cloud';
+export interface ResolvedDeploymentConfig {
+    runtimeMode: RuntimeMode;
+    cloudEnvironment: TaskforceCloudEnvironment | null;
+    cloudBaseUrl: string;
+    cloudMcpBaseUrl: string;
+    baseUrl: string;
+    apiBaseUrl: string;
+    cloudAuthBaseUrl: string;
+    wsBaseUrl: string;
+    cloudAuthViaLocalProxy: boolean;
+    warnings: string[];
+}
+export interface ResolveDeploymentConfigOptions {
+    onWarning?: CompatWarningHandler;
+    requestBaseUrl?: string | null;
+}
+export declare function resolveDeploymentConfig(env: EnvLike, options?: ResolveDeploymentConfigOptions): ResolvedDeploymentConfig;

package/dist/config/deployment.js

@@ -0,0 +1,67 @@
+import { TASKFORCE_CLOUD_ENVIRONMENTS, parseTaskforceCloudEnvironment } from './cloudEnvironment.js';
+import { resolveCompatCloudEnvironment } from '../compat/deploymentCompat.js';
+function readEnvValue(env, key) {
+    return String(env[key] || '').trim();
+}
+function normalizeRuntimeMode(raw) {
+    return raw.toLowerCase() === 'cloud' ? 'cloud' : 'local';
+}
+function normalizeHttpUrl(raw) {
+    return String(raw || '').trim().replace(/\/+$/, '');
+}
+function normalizeWsUrl(raw) {
+    return String(raw || '').trim().replace(/\/+$/, '');
+}
+function firstNonEmpty(...values) {
+    for (const value of values) {
+        if (String(value || '').trim())
+            return String(value || '').trim();
+    }
+    return '';
+}
+export function resolveDeploymentConfig(env, options = {}) {
+    const warnings = [];
+    const onWarning = (message) => {
+        warnings.push(message);
+        options.onWarning?.(message);
+    };
+    const runtimeMode = normalizeRuntimeMode(readEnvValue(env, 'TASKFORCE_RUNTIME_MODE'));
+    const explicitCloudEnvironment = parseTaskforceCloudEnvironment(readEnvValue(env, 'TASKFORCE_CLOUD_ENVIRONMENT'));
+    const compatCloudEnvironment = explicitCloudEnvironment
+        ? { cloudEnvironment: explicitCloudEnvironment, warnings: [] }
+        : resolveCompatCloudEnvironment(env, onWarning);
+    const cloudEnvironment = explicitCloudEnvironment || compatCloudEnvironment.cloudEnvironment;
+    const requestBaseUrl = normalizeHttpUrl(String(options.requestBaseUrl || ''));
+    const explicitBaseUrl = normalizeHttpUrl(firstNonEmpty(readEnvValue(env, 'VITE_TASKFORCE_BASE_URL'), readEnvValue(env, 'TASKFORCE_BASE_URL')));
+    const explicitApiBaseUrl = normalizeHttpUrl(readEnvValue(env, 'VITE_TASKFORCE_API_BASE_URL'));
+    const explicitCloudAuthBaseUrl = normalizeHttpUrl(readEnvValue(env, 'VITE_TASKFORCE_CLOUD_AUTH_BASE_URL'));
+    const explicitCloudMcpBaseUrl = normalizeHttpUrl(firstNonEmpty(readEnvValue(env, 'VITE_TASKFORCE_CLOUD_MCP_BASE_URL'), readEnvValue(env, 'TASKFORCE_CLOUD_MCP_BASE_URL')));
+    const explicitCloudProxyBaseUrl = normalizeHttpUrl(readEnvValue(env, 'TASKFORCE_CLOUD_PROXY_BASE_URL'));
+    const explicitWsBaseUrl = normalizeWsUrl(readEnvValue(env, 'VITE_TASKFORCE_WS_BASE_URL'));
+    const canonicalCloudBaseUrl = cloudEnvironment
+        ? TASKFORCE_CLOUD_ENVIRONMENTS[cloudEnvironment].appBaseUrl
+        : '';
+    const canonicalCloudMcpBaseUrl = cloudEnvironment
+        ? TASKFORCE_CLOUD_ENVIRONMENTS[cloudEnvironment].mcpBaseUrl
+        : '';
+    const cloudBaseUrl = firstNonEmpty(explicitCloudProxyBaseUrl, explicitCloudAuthBaseUrl, explicitApiBaseUrl, explicitBaseUrl, canonicalCloudBaseUrl);
+    const cloudMcpBaseUrl = firstNonEmpty(explicitCloudMcpBaseUrl, canonicalCloudMcpBaseUrl, cloudBaseUrl);
+    const baseUrl = firstNonEmpty(requestBaseUrl, explicitBaseUrl, explicitApiBaseUrl, explicitCloudAuthBaseUrl, cloudBaseUrl);
+    const apiBaseUrl = firstNonEmpty(requestBaseUrl, explicitApiBaseUrl, explicitBaseUrl, cloudBaseUrl);
+    const cloudAuthBaseUrl = firstNonEmpty(requestBaseUrl, explicitCloudAuthBaseUrl, explicitBaseUrl, explicitApiBaseUrl, cloudBaseUrl);
+    const wsBaseUrl = runtimeMode === 'local'
+        ? firstNonEmpty(explicitWsBaseUrl, requestBaseUrl, explicitApiBaseUrl, explicitBaseUrl, explicitCloudProxyBaseUrl, explicitCloudAuthBaseUrl, canonicalCloudBaseUrl, cloudBaseUrl)
+        : firstNonEmpty(requestBaseUrl, explicitWsBaseUrl, apiBaseUrl, baseUrl, cloudBaseUrl);
+    return {
+        runtimeMode,
+        cloudEnvironment,
+        cloudBaseUrl,
+        cloudMcpBaseUrl,
+        baseUrl,
+        apiBaseUrl,
+        cloudAuthBaseUrl,
+        wsBaseUrl,
+        cloudAuthViaLocalProxy: Boolean(explicitCloudProxyBaseUrl),
+        warnings
+    };
+}

package/dist/config/deployment.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config/deployment.test.js

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import { resolveDeploymentConfig } from './deployment';
+describe('config/deployment', () => {
+    it('defaults runtime mode to local without inferring from db provider', () => {
+        const deployment = resolveDeploymentConfig({
+            TASKFORCE_DB_PROVIDER: 'postgres'
+        });
+        expect(deployment.runtimeMode).toBe('local');
+        expect(deployment.cloudEnvironment).toBe(null);
+    });
+    it('resolves canonical cloud environment into cloud endpoints', () => {
+        const deployment = resolveDeploymentConfig({
+            TASKFORCE_RUNTIME_MODE: 'cloud',
+            TASKFORCE_CLOUD_ENVIRONMENT: 'staging'
+        });
+        expect(deployment.runtimeMode).toBe('cloud');
+        expect(deployment.cloudEnvironment).toBe('staging');
+        expect(deployment.cloudBaseUrl).toBe('https://staging-app.taskforcehq.ai');
+        expect(deployment.cloudMcpBaseUrl).toBe('https://staging-mcp.taskforcehq.ai');
+        expect(deployment.apiBaseUrl).toBe('https://staging-app.taskforcehq.ai');
+        expect(deployment.cloudAuthBaseUrl).toBe('https://staging-app.taskforcehq.ai');
+        expect(deployment.wsBaseUrl).toBe('https://staging-app.taskforcehq.ai');
+    });
+    it('keeps request-origin precedence for base/api urls and local-runtime websockets', () => {
+        const deployment = resolveDeploymentConfig({
+            TASKFORCE_RUNTIME_MODE: 'local',
+            TASKFORCE_CLOUD_ENVIRONMENT: 'production',
+            VITE_TASKFORCE_API_BASE_URL: 'https://app.taskforcehq.ai'
+        }, {
+            requestBaseUrl: 'http://127.0.0.1:5174'
+        });
+        expect(deployment.baseUrl).toBe('http://127.0.0.1:5174');
+        expect(deployment.apiBaseUrl).toBe('http://127.0.0.1:5174');
+        expect(deployment.cloudAuthBaseUrl).toBe('http://127.0.0.1:5174');
+        expect(deployment.wsBaseUrl).toBe('http://127.0.0.1:5174');
+        expect(deployment.cloudMcpBaseUrl).toBe('https://mcp.taskforcehq.ai');
+    });
+    it('keeps local-runtime websockets on the request origin even when cloud proxying is configured', () => {
+        const deployment = resolveDeploymentConfig({
+            TASKFORCE_RUNTIME_MODE: 'local',
+            TASKFORCE_CLOUD_ENVIRONMENT: 'staging',
+            TASKFORCE_CLOUD_PROXY_BASE_URL: 'https://staging-app.taskforcehq.ai'
+        }, {
+            requestBaseUrl: 'http://127.0.0.1:5174'
+        });
+        expect(deployment.baseUrl).toBe('http://127.0.0.1:5174');
+        expect(deployment.apiBaseUrl).toBe('http://127.0.0.1:5174');
+        expect(deployment.cloudAuthBaseUrl).toBe('http://127.0.0.1:5174');
+        expect(deployment.wsBaseUrl).toBe('http://127.0.0.1:5174');
+    });
+    it('still honors an explicit websocket override in local runtime', () => {
+        const deployment = resolveDeploymentConfig({
+            TASKFORCE_RUNTIME_MODE: 'local',
+            TASKFORCE_CLOUD_ENVIRONMENT: 'staging',
+            TASKFORCE_CLOUD_PROXY_BASE_URL: 'https://staging-app.taskforcehq.ai',
+            VITE_TASKFORCE_WS_BASE_URL: 'https://ws-proxy.example.com'
+        }, {
+            requestBaseUrl: 'http://127.0.0.1:5174'
+        });
+        expect(deployment.wsBaseUrl).toBe('https://ws-proxy.example.com');
+    });
+    it('keeps legacy URL-only configuration working with compat warnings', () => {
+        const deployment = resolveDeploymentConfig({
+            VITE_TASKFORCE_API_BASE_URL: 'https://performance-app.taskforcehq.ai'
+        });
+        expect(deployment.cloudEnvironment).toBe('performance');
+        expect(deployment.cloudMcpBaseUrl).toBe('https://performance-mcp.taskforcehq.ai');
+        expect(deployment.apiBaseUrl).toBe('https://performance-app.taskforcehq.ai');
+        expect(deployment.warnings.join('\n')).toContain('VITE_TASKFORCE_API_BASE_URL');
+    });
+    it('uses an explicit MCP base URL when provided', () => {
+        const deployment = resolveDeploymentConfig({
+            TASKFORCE_RUNTIME_MODE: 'cloud',
+            TASKFORCE_CLOUD_ENVIRONMENT: 'production',
+            VITE_TASKFORCE_CLOUD_MCP_BASE_URL: 'https://mcp.taskforcehq.ai'
+        });
+        expect(deployment.cloudBaseUrl).toBe('https://app.taskforcehq.ai');
+        expect(deployment.cloudMcpBaseUrl).toBe('https://mcp.taskforcehq.ai');
+        expect(deployment.cloudAuthBaseUrl).toBe('https://app.taskforcehq.ai');
+    });
+    it('accepts legacy ENV alias for site builds during compat mode', () => {
+        const deployment = resolveDeploymentConfig({
+            ENV: 'staging'
+        });
+        expect(deployment.cloudEnvironment).toBe('staging');
+        expect(deployment.warnings.join('\n')).toContain('ENV=staging');
+    });
+});

package/dist/config/envSchema.js

@@ -1,8 +1,11 @@
+import { resolveDeploymentConfig } from './deployment.js';
+import { MIGRATION_COMPAT_ENABLED } from '../runtime/migrationFlags.js';
 const SPECS = [
     { key: 'PORT', description: 'Standalone server port.', category: 'Core', defaultValue: '8080', targets: ['server', 'all'] },
     { key: 'TASKFORCE_TENANT_ID', description: 'Tenant identifier.', category: 'Core', defaultValue: 'default', targets: ['server', 'all'] },
     { key: 'TASKFORCE_WORKSPACE_ID', description: 'Optional explicit workspace scope for MCP/server tooling.', category: 'Core', targets: ['server', 'all'] },
     { key: 'TASKFORCE_RUNTIME_MODE', description: 'Runtime mode (local|cloud).', category: 'Core', defaultValue: 'local', example: 'cloud', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_CLOUD_ENVIRONMENT', description: 'Canonical cloud target (production|staging|performance).', category: 'Core', defaultValue: 'production', example: 'staging', targets: ['server', 'all'] },
     { key: 'TASKFORCE_DB_PROVIDER', description: 'Database provider (sqlite|postgres).', category: 'Core', defaultValue: 'sqlite', example: 'postgres', targets: ['server', 'all'] },
     { key: 'TASKFORCE_BILLING_ENABLED', description: 'Enable Stripe billing routes and webhook processing.', category: 'Core', defaultValue: 'false', targets: ['server', 'all'] },
     { key: 'TASKFORCE_DATABASE_URL', description: 'Postgres connection string when provider=postgres.', category: 'Core', example: 'postgresql://user:pass@host:5432/db', secret: true, targets: ['server', 'all'] },
@@ -10,11 +13,10 @@ const SPECS = [
     { key: 'TASKFORCE_FORCE_SETUP', description: 'Force local setup gate for development.', category: 'Core', defaultValue: 'false', targets: ['server', 'all'] },
     { key: 'TASKFORCE_FORCE_GLOBAL_SETUP', description: 'Force global setup step for development.', category: 'Core', defaultValue: 'false', targets: ['server', 'all'] },
     { key: 'TASKFORCE_FORCE_WORKSPACE_SETUP', description: 'Force workspace setup step for development.', category: 'Core', defaultValue: 'false', targets: ['server', 'all'] },
-    { key: 'TASKFORCE_GIT_BACKUP', description: 'Enable git backup persistence behavior in local tooling.', category: 'Core', defaultValue: 'false', targets: ['server', 'all'] },
     { key: 'TASKFORCE_REALTIME_SYNC', description: 'Enable realtime sync transport layer (feature-flag).', category: 'Core', defaultValue: 'false', targets: ['server', 'all'] },
     { key: 'TASKFORCE_AUTH_ENABLED', description: 'Enable auth endpoints and session checks.', category: 'Auth', defaultValue: 'true', targets: ['server', 'all'] },
     { key: 'TASKFORCE_AUTH_REQUIRED_FOR_API', description: 'Require auth for protected API routes.', category: 'Auth', defaultValue: 'true', targets: ['server', 'all'] },
-    { key: 'TASKFORCE_AUTH_EXCLUDED_PATHS', description: 'Comma-separated API paths excluded from auth checks.', category: 'Auth', defaultValue: '/api/taskforce/health,/api/taskforce/version,/api/taskforce/auth', targets: ['server', 'all'] },
+    { key: 'TASKFORCE_AUTH_EXCLUDED_PATHS', description: 'Comma-separated API paths excluded from auth checks.', category: 'Auth', defaultValue: '/api/taskforce/health,/api/taskforce/version,/api/taskforce/auth,/api/taskforce/public/pricing,/api/taskforce/public/site-config,/api/taskforce/public/site-config-script', targets: ['server', 'all'] },
     { key: 'TASKFORCE_AUTH_DEFAULT_ROLE', description: 'Default role for unauthenticated context (owner|admin|member|read-only).', category: 'Auth', defaultValue: 'member', targets: ['server', 'all'] },
     { key: 'TASKFORCE_AUTH_SESSION_COOKIE', description: 'Session cookie name.', category: 'Auth', defaultValue: 'taskforce_session', targets: ['server', 'all'] },
     { key: 'TASKFORCE_AUTH_SESSION_SECRET', description: 'Session signing secret.', category: 'Auth', secret: true, targets: ['server', 'all'] },
@@ -35,7 +37,7 @@ const SPECS = [
     { key: 'R2_ACCESS_KEY_ID', description: 'R2 access key ID.', category: 'Storage', secret: true, targets: ['server', 'all'] },
     { key: 'R2_SECRET_ACCESS_KEY', description: 'R2 secret access key.', category: 'Storage', secret: true, targets: ['server', 'all'] },
     { key: 'R2_ENDPOINT', description: 'Optional R2 endpoint override.', category: 'Storage', targets: ['server', 'all'] },
-    { key: 'R2_KEY_PREFIX', description: 'R2 key prefix.', category: 'Storage', defaultValue: 'taskforce', targets: ['server', 'all'] },
+    { key: 'R2_KEY_PREFIX', description: 'Optional R2 key prefix.', category: 'Storage', defaultValue: '', targets: ['server', 'all'] },
     { key: 'R2_SIGNED_UPLOAD_TTL_SECONDS', description: 'Upload signed URL TTL.', category: 'Storage', defaultValue: '600', targets: ['server', 'all'] },
     { key: 'R2_SIGNED_DOWNLOAD_TTL_SECONDS', description: 'Download signed URL TTL.', category: 'Storage', defaultValue: '300', targets: ['server', 'all'] },
     { key: 'TASKFORCE_VIRUS_SCAN_PROVIDER', description: 'Virus scanner provider (none|clamav).', category: 'Security', defaultValue: 'none', targets: ['server', 'all'] },
@@ -68,9 +70,11 @@ const SPECS = [
     { key: 'TASKFORCE_BUILD_GIT_SHA', description: 'Build git SHA metadata.', category: 'Build', targets: ['server', 'all'] },
     { key: 'TASKFORCE_BUILD_TIME', description: 'Build timestamp metadata.', category: 'Build', targets: ['server', 'all'] },
     { key: 'TASKFORCE_BUILD_DEPLOY_ID', description: 'Build deploy ID metadata.', category: 'Build', targets: ['server', 'all'] },
+    { key: 'DEBUG_MODE', description: 'Expose debug-only client diagnostics such as pricing source metadata.', category: 'Build', defaultValue: 'false', targets: ['all'] },
     { key: 'VITE_TASKFORCE_BASE_URL', description: 'Client base URL for both API and cloud auth when specific overrides are not set.', category: 'Client', example: 'https://performance-app.taskforcehq.ai', targets: ['all'] },
     { key: 'VITE_TASKFORCE_API_BASE_URL', description: 'Client API base URL (overrides VITE_TASKFORCE_BASE_URL when set).', category: 'Client', example: 'https://performance-app.taskforcehq.ai', targets: ['all'] },
     { key: 'VITE_TASKFORCE_CLOUD_AUTH_BASE_URL', description: 'Client cloud auth base URL.', category: 'Client', example: 'https://performance-app.taskforcehq.ai', targets: ['all'] },
+    { key: 'VITE_TASKFORCE_CLOUD_MCP_BASE_URL', description: 'Client cloud MCP base URL.', category: 'Client', example: 'https://performance-mcp.taskforcehq.ai', targets: ['all'] },
     { key: 'VITE_TASKFORCE_WS_BASE_URL', description: 'Client websocket base URL override.', category: 'Client', example: 'wss://performance-app.taskforcehq.ai', targets: ['all'] },
     { key: 'SYNC_SOAK_LOCAL_BASE_URL', description: 'Soak local app URL.', category: 'Soak', defaultValue: 'http://localhost:5174', targets: ['soak', 'all'] },
     { key: 'SYNC_SOAK_CLOUD_BASE_URL', description: 'Soak cloud app URL.', category: 'Soak', example: 'https://performance-app.taskforcehq.ai', targets: ['soak', 'all'] },
@@ -172,19 +176,43 @@ function validateCommonNumbers(env, errors) {
         }
     }
 }
-function validateServerEnv(env, errors) {
+function validateServerEnv(env, errors, warnings) {
     const providerRaw = String(env.TASKFORCE_DB_PROVIDER || 'sqlite').trim().toLowerCase();
     const provider = providerRaw === 'postgres' ? 'postgres' : 'sqlite';
     if (!['sqlite', 'postgres'].includes(providerRaw) && providerRaw !== '') {
         errors.push('TASKFORCE_DB_PROVIDER must be one of: sqlite, postgres.');
     }
+    const deployment = resolveDeploymentConfig(env);
     const runtimeRaw = String(env.TASKFORCE_RUNTIME_MODE || '').trim().toLowerCase();
-    const runtimeMode = runtimeRaw === 'cloud' || runtimeRaw === 'local'
-        ? runtimeRaw
-        : (provider === 'postgres' ? 'cloud' : 'local');
+    const runtimeMode = deployment.runtimeMode;
     if (runtimeRaw && !['local', 'cloud'].includes(runtimeRaw)) {
         errors.push('TASKFORCE_RUNTIME_MODE must be one of: local, cloud.');
     }
+    const cloudEnvironmentRaw = String(env.TASKFORCE_CLOUD_ENVIRONMENT || '').trim().toLowerCase();
+    if (cloudEnvironmentRaw && !['production', 'staging', 'performance'].includes(cloudEnvironmentRaw)) {
+        errors.push('TASKFORCE_CLOUD_ENVIRONMENT must be one of: production, staging, performance.');
+    }
+    warnings.push(...deployment.warnings);
+    const cloudTargetConfigured = runtimeMode === 'cloud'
+        || hasValue(env, 'TASKFORCE_CLOUD_ENVIRONMENT')
+        || hasValue(env, 'TASKFORCE_CLOUD_PROXY_BASE_URL')
+        || hasValue(env, 'VITE_TASKFORCE_CLOUD_AUTH_BASE_URL')
+        || hasValue(env, 'VITE_TASKFORCE_CLOUD_MCP_BASE_URL')
+        || hasValue(env, 'VITE_TASKFORCE_API_BASE_URL')
+        || hasValue(env, 'VITE_TASKFORCE_BASE_URL')
+        || hasValue(env, 'TASKFORCE_BASE_URL')
+        || hasValue(env, 'TASKFORCE_AUTH_PUBLIC_BASE_URL');
+    if (cloudTargetConfigured && !deployment.cloudEnvironment) {
+        if (MIGRATION_COMPAT_ENABLED) {
+            warnings.push('TASKFORCE_CLOUD_ENVIRONMENT is not set and could not be inferred from legacy cloud URL configuration.');
+        }
+        else {
+            errors.push('TASKFORCE_CLOUD_ENVIRONMENT is required when cloud runtime or cloud-targeted features are configured.');
+        }
+    }
+    else if (cloudTargetConfigured && !hasValue(env, 'TASKFORCE_CLOUD_ENVIRONMENT') && deployment.cloudEnvironment) {
+        warnings.push(`TASKFORCE_CLOUD_ENVIRONMENT is not set; resolved ${deployment.cloudEnvironment} from compatibility inputs.`);
+    }
     const allowSqliteInCloud = parseBoolean(env.TASKFORCE_ALLOW_SQLITE_IN_CLOUD) === true;
     const billingEnabled = parseBoolean(env.TASKFORCE_BILLING_ENABLED) === true;
     if (runtimeMode === 'cloud' && provider !== 'postgres' && !allowSqliteInCloud) {
@@ -307,7 +335,7 @@ export function validateEnvironment(env = process.env, options = {}) {
     const warnings = [];
     validateCommonNumbers(env, errors);
     if (target === 'server' || target === 'all') {
-        validateServerEnv(env, errors);
+        validateServerEnv(env, errors, warnings);
     }
     if (target === 'soak' || target === 'all') {
         validateSoakEnv(env, errors);

package/dist/config/envSchema.test.js

@@ -4,6 +4,7 @@ describe('config/envSchema', () => {
     it('fails server validation when cloud runtime is configured without postgres', () => {
         const result = validateEnvironment({
             TASKFORCE_RUNTIME_MODE: 'cloud',
+            TASKFORCE_CLOUD_ENVIRONMENT: 'production',
             TASKFORCE_DB_PROVIDER: 'sqlite',
             TASKFORCE_AUTH_ENABLED: 'false'
         }, { target: 'server', strictUnknown: false });
@@ -28,6 +29,7 @@ describe('config/envSchema', () => {
     it('rejects unknown email provider', () => {
         const result = validateEnvironment({
             TASKFORCE_RUNTIME_MODE: 'cloud',
+            TASKFORCE_CLOUD_ENVIRONMENT: 'production',
             TASKFORCE_DB_PROVIDER: 'postgres',
             TASKFORCE_DATABASE_URL: 'postgresql://localhost/test',
             TASKFORCE_AUTH_ENABLED: 'false',
@@ -39,6 +41,7 @@ describe('config/envSchema', () => {
     it('requires google workspace app password when provider is google-workspace', () => {
         const result = validateEnvironment({
             TASKFORCE_RUNTIME_MODE: 'cloud',
+            TASKFORCE_CLOUD_ENVIRONMENT: 'production',
             TASKFORCE_DB_PROVIDER: 'postgres',
             TASKFORCE_DATABASE_URL: 'postgresql://localhost/test',
             TASKFORCE_AUTH_ENABLED: 'false',
@@ -50,6 +53,7 @@ describe('config/envSchema', () => {
     it('accepts google workspace provider with google app password alias', () => {
         const result = validateEnvironment({
             TASKFORCE_RUNTIME_MODE: 'cloud',
+            TASKFORCE_CLOUD_ENVIRONMENT: 'production',
             TASKFORCE_DB_PROVIDER: 'postgres',
             TASKFORCE_DATABASE_URL: 'postgresql://localhost/test',
             TASKFORCE_AUTH_ENABLED: 'false',
@@ -61,6 +65,7 @@ describe('config/envSchema', () => {
     it('requires TASKFORCE_STRIPE_SECRET_KEY when billing is enabled', () => {
         const result = validateEnvironment({
             TASKFORCE_RUNTIME_MODE: 'cloud',
+            TASKFORCE_CLOUD_ENVIRONMENT: 'production',
             TASKFORCE_DB_PROVIDER: 'postgres',
             TASKFORCE_DATABASE_URL: 'postgresql://localhost/test',
             TASKFORCE_AUTH_ENABLED: 'false',
@@ -73,6 +78,7 @@ describe('config/envSchema', () => {
     it('requires TASKFORCE_STRIPE_WEBHOOK_SECRET when billing is enabled', () => {
         const result = validateEnvironment({
             TASKFORCE_RUNTIME_MODE: 'cloud',
+            TASKFORCE_CLOUD_ENVIRONMENT: 'production',
             TASKFORCE_DB_PROVIDER: 'postgres',
             TASKFORCE_DATABASE_URL: 'postgresql://localhost/test',
             TASKFORCE_AUTH_ENABLED: 'false',
@@ -85,6 +91,7 @@ describe('config/envSchema', () => {
     it('requires cloud runtime when billing is enabled', () => {
         const result = validateEnvironment({
             TASKFORCE_RUNTIME_MODE: 'local',
+            TASKFORCE_CLOUD_ENVIRONMENT: 'production',
             TASKFORCE_DB_PROVIDER: 'sqlite',
             TASKFORCE_AUTH_ENABLED: 'false',
             TASKFORCE_BILLING_ENABLED: 'true',
@@ -94,4 +101,25 @@ describe('config/envSchema', () => {
         expect(result.ok).toBe(false);
         expect(result.errors.join('\n')).toContain('TASKFORCE_BILLING_ENABLED requires TASKFORCE_RUNTIME_MODE=cloud.');
     });
+    it('warns when inferring cloud environment from legacy URL inputs', () => {
+        const result = validateEnvironment({
+            TASKFORCE_RUNTIME_MODE: 'local',
+            TASKFORCE_DB_PROVIDER: 'sqlite',
+            VITE_TASKFORCE_API_BASE_URL: 'https://performance-app.taskforcehq.ai'
+        }, { target: 'server', strictUnknown: false });
+        expect(result.ok).toBe(true);
+        expect(result.warnings.join('\n')).toContain('VITE_TASKFORCE_API_BASE_URL');
+    });
+    it('accepts VITE_TASKFORCE_CLOUD_MCP_BASE_URL as a managed environment variable', () => {
+        const result = validateEnvironment({
+            TASKFORCE_RUNTIME_MODE: 'cloud',
+            TASKFORCE_CLOUD_ENVIRONMENT: 'performance',
+            TASKFORCE_DB_PROVIDER: 'postgres',
+            TASKFORCE_DATABASE_URL: 'postgresql://localhost/test',
+            TASKFORCE_AUTH_ENABLED: 'false',
+            VITE_TASKFORCE_CLOUD_MCP_BASE_URL: 'https://performance-mcp.taskforcehq.ai'
+        }, { target: 'server', strictUnknown: true });
+        expect(result.ok).toBe(true);
+        expect(result.errors).toEqual([]);
+    });
 });

package/dist/core/AiProfileService.d.ts

@@ -0,0 +1,66 @@
+import type { DatabaseAdapter } from '../storage/databaseAdapter.js';
+import { type AiProfileSurfaceType } from '../shared/aiProfileSurfaceType.js';
+export interface AiProfileRecordLike {
+    id: string;
+    workspaceId: string;
+    profileToken: string;
+    name: string;
+    username: string;
+    icon: string;
+    color: string;
+    description?: string | null;
+    role?: string | null;
+    provider?: string | null;
+    model?: string | null;
+    surfaceType?: AiProfileSurfaceType | null;
+    providerMetadata?: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt: string;
+    lastActiveAt?: string | null;
+}
+export interface ResolveAiProfileInputLike {
+    workspaceId: string;
+    name: string;
+    profileToken?: string | null;
+    icon?: string | null;
+    color?: string | null;
+    description?: string | null;
+    role?: string | null;
+    provider?: string | null;
+    model?: string | null;
+    surfaceType?: AiProfileSurfaceType | null;
+    providerMetadata?: Record<string, unknown> | null;
+}
+export interface ResolveAiProfileResultLike {
+    created: boolean;
+    profile: AiProfileRecordLike;
+    duplicateWarning?: {
+        existingProfileId: string;
+        message: string;
+    };
+}
+export interface AiProfileServiceDeps {
+    db: DatabaseAdapter;
+    tenantId: string;
+    normalizeWorkspaceId: (workspaceId: string) => string;
+    normalizeAiProfileName: (name: unknown) => string;
+    normalizeAiProfileUsername: (value: unknown, fallbackName: string) => string;
+    normalizeAiProfileIcon: (value: unknown) => string;
+    normalizeAiProfileColor: (value: unknown) => string;
+    aiProfileRowToRecord: (row: Record<string, unknown>) => AiProfileRecordLike;
+    generateEntityId: (prefix: string) => string;
+    issueProfileToken: () => string;
+    createRuleError: (message: string, statusCode?: number, code?: string) => Error;
+}
+export declare function listAiProfilesService(deps: AiProfileServiceDeps, workspaceId: string): AiProfileRecordLike[];
+export declare function getAiProfileByTokenService(deps: AiProfileServiceDeps, input: {
+    workspaceId: string;
+    profileToken: string;
+}): AiProfileRecordLike | null;
+export declare function upsertAiProfileForSyncService(deps: AiProfileServiceDeps, profile: AiProfileRecordLike): AiProfileRecordLike;
+export declare function mergeAiProfilesService(deps: AiProfileServiceDeps, input: {
+    workspaceId: string;
+    keepId: string;
+    mergeId: string;
+}): AiProfileRecordLike;
+export declare function resolveAiProfileService(deps: AiProfileServiceDeps, input: ResolveAiProfileInputLike): ResolveAiProfileResultLike;